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Alto Subsystems 



This document is a directory of major Alto BCPL subsystems. Mesa subsystems are 
collected together and documented elsewhere. 

Binary versions of these programs are available on the <ALTO> directory. If the 
documentation for the subsystem is short, it is included in this file directly. If it is 
somewhat longer, the documentation is stored separately and the entry is marked with a *. 
The documentation for these objects is available on <ALTODOCS> in .TTY files. Programs 
that have quite bulky documentation are denoted by **. These programs have separate 
documentation on <ALTODOCS>, usually as <ALTODOCS>name.EARS. 

If you would like a full listing of documentation for all but the ** programs give the 
command "EARS <ALTODOCS>'SUBSYSTEMS.EARS". 

The person last known to be responsible for each subsystem is also given. 

*ANSRV: a program that permits a Nova to be used from an Alto as a "remote batch" 
computer. (Bruce Parsley) 

*ASM: an assembler for Alto machine language, producing object files compatible with 
the Bcpl loader. (Ed McCreight) 

**BCPL: a compiler fch" the Bcpl language. (Dan Swinehart) 

**BLDR: a loader for object files produced by Bcpl and Asm. It is documented in the 
Bcpl manual. (Dan Swinehart) 

**BRAVO: a display editor. (Charles Simonyi) 

*BUILDBOOT: a program for constructing Alto boot files. (Ed McCreight) 

*CHAT: establishes PUP Telnet connections between a pair of cooperating parties. 
(Bob Sproull) 

CLEANDIR: does a garbage collection on a file directory (not on the disk space, 
though). Call it with 
>CLEANDIR directory-name n 

to clean up the specified directory. The system directory is called SYSDIR. The 
second parameter, n, tells how much extra space to append to the directory. The 
reason for it is that extending the directory in this way will tend to get the pages 
allocated to consecutive disk sectors, so that subsequent lookups will go faster. If 
this program fails, it will leave your disk unusable. To guard against this, you can 
copy SYSDIR to a dummy file and run CLEANDIR on that first, then run it again 
on SYSDIR. DO NOT try to copy the cleaned-up dummy file back to SYSDIR. 
(Butler Lampson) 

*COPYDISK: is run on an Alto with a dual disk drive to copy an entire disk to a new 
disk; it may also be run on a standard Alto to copy entire disks over the Ethernet. 
All old data on the disk to which you copy is destroyed. (David Bog,gs) 

*CREATEFILE: creates a file of a given size, allocating consecutively if possible. 
(Peter Deutsch) 

*DDS: The Descriptive Directory System is a front end for the Alto file system, 
providing a relational data base management system and facilities for displaying 



information related to Alto files. (Peter Deutsch) 
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*DMT.BOOT: Alto memory diagnostic program and related statistics-gathering 
programs. (D;vid Boggs) 

♦DPRINT: Prints disk files on the Diablo Printer. (Ed Taft) 

**DRAW: An illustrator. (Patrick Beaudelaire) 

EMPRESS: Converts ordinary text files to Press files, and performs simple formatting 
operations. (David Boggs) 

♦EXECUTIVE: The Alto command processor. (Ed McCreight) 

The following commands are a part of the EXEC: 

BOOTFROM: allows you to initiate a software boot of your Alto from an 

arbitrary file on the disk. 

BOOTKEYS: tells you what keys to hold down to boot from a file. 

COPY: copies from one file to another. 

Dl ACINOSE: invokes the memory diagnostic, DMT. 

DELETE: deletes files. 

DUMP: dumps a set of files onto a single "dump" file which can be 

manipulated as a unit. The files can be recovered later by a LOAD. There is 

also a Maxc subsystem called DUMP-LOAD which will do DUMPs and LOADs 

on Maxc. 

Fl LEST AT: displays attributes of files (length, creation date, etc.). The files 

mav be specified by name or serial number. 

INSTALL: installs Sys.Boot, or the file specified. Install allows you to erase an 

old disk and create a new one. Refer to the Operating System manual for 

documentation of Install. 

LOAD: reads a file produced by DUMP and extracts the embedded files. 

LOGIN: stores user name and password in the resident system to be provided 

to subsystems which deal with access-controlled resources. 

QUIT: terminates the operating system. 

RELEASE: displays the version number and date of the currently running 

operating system. 

RENAME: renames files. 

RESUME: restarts a resumable file. Call it with 

> RESUME file 

If file is omitted, SWATEE is assumed. 

SETTIME: sets the date and time. 

STANDARDRAM: loads the Ram with a standard package. (See documentation 

for RAMLOAD). 

TYPE: types text files. 

*FIND: a program to search text files for user-supplied strings. This program 
originated as a demonstration of the power of compiling microcode from the given 
problem. (Peter Deutsch) 

*FTP: a Pup-based File Transfer Program for moving files to and from an Alto file 
system. (David Boggs) 

♦GEARS, FEARS, DEFAULT.ED: sends files over the Ethernet to be printed on 
EARS. (David Boggs) 

♦LISTSYMS: converts the .Syms file produced by BLDR into human readable form. 
(Peter Deutsch) 

♦MAILCHECK: A program that will check for waiting MAXC mail. (Larry Masinter) 
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**MARKUP: A document illustrator. (William Newman) 

MICRO: The microcode assembler for Maxc, Dorado, DO, and other machines. Basic 
documentation is available only in the CSL archives. It is called "Maxc document 
9.2". Recent changes are documented in <AkoDocs>Micro.tty. (Peter Deutsch) 

MOVETOKEYS: Moves page 1 of the named file to the appropriate page of the disk 
so that depressing the key-combination and the boot button will boot-load the file. 
Whatever v/as on that page before is moved to the original page 1 of the file; i.e. 
tl e two paces are swapped, and the necessary pointers are fixed up. The legal keys 
are 5,4,6, 7,D.E,K,P,U,V,0,-,/, and A. If you want to tvpe 7" to MoveToKeys type 
"?" instead. 
Examples: 

MOVETOKEYS DUMPER DU is a typical call 

MoveToKeys BOOT 5?6 allows one to invoke BOOT by holding dov/n 5,/, and 6. 
(Jim Morris) 

*MU: The microcode assembler for the Alto. (Chuck Thacker) 

*NE:TEXEC: This subsystem, which is bootstrapped over the Ethernet, provides a 
convenient interface to the other systems available from "boot servers" on the 
network. (David Boggs) 

*OEDIT: allows you to look at and modify arbitrary files in octal. (Butler Lampson) 

*ORAM: A scheme for overlaying several segments of microcode in the Alto RAM. 
(Peter Deutsch) 

*PACKMU/RPRAM: These two subsystems, in conjunction with the subroutine 
ReadPRAM or LoadRam, allow programs using the RAM to check the constant 
memory and load the RAM as a part of their initialization. (Peter Deutsch) 

*PEEKPUP: a Pup software debugging aid. (Ed Taft) 

**PREPRESS: A program for manipulating font files. (Bob Sproull) 

*PRESSEDIT: combines Press files, converts Ears files into Press format, or adds extra 
fonts to a Press file. (William Newman) 

*PRINT: can be used to print any Press file on Ears via Maxc. That is its only use. 
EmPress should be used to send Press files to Press printers. (William Newman) 

PROOFREADER: Proofreader for English text. (Ed McCreight) 

PUT: A program for listing, copying, and deleting files. It is capable of dealing with 
both drives of a two-drive Alto. The program offers help on its use. (Keith Knox 
- WRC) 

*QED: a teletype-oriented editor. 

*RAMLOAD: a program for loading the Alto RAM from the files produced by the 
microcode assembler, MU. (Dave Boggs) 

READPRESS: reads Press files and displays a text-listing of the entity commands, DL 
strings, etc. Command line is of the form: "ReadPress Test.Press". (Joe Maleson) 

RENAME: renames a file quickly. Call it by typing: 
>Rename oldFileName newFileName (David Boggs) 

^SCAVENGER: a subsystem for checking and correcting disk packs. (Jim Morris) 



For Xerox Internal Use Only — April 29, 1978 
Alto Subsystems April 29, 1978 



**SIL, Analyze, Gobble, GPR, PPR, Etc.:A system for automating logic design, 
includeing an illustrator specialized to logic drawings. (Chuck Thacker) 

SORT: a very small subsystem which will sort files containing less than 1000 entries, 
each terminated by a carriage return. Call it with 

>SORT <sortfilein> <sortfileout> 

If <sortfileout> is omitted, the sorted data will be written back to <sortfilein>. 
(Barbara Hunt) 

*SWAT: a debugger for Bcpl programs. (Jim Morris) 

SYS. BOOT: is the name of the boot file for the operating system on the Alto disk. 
(David Boggs) 

Trident disk software: TFU, TRIEX and the TFS software package. The Bcpl 
software package and utility programs for driving Trident disks interfaced to the 
Alto. (Ed Taft) 

""VIEWDATA:' a subsystem that displays 2D projections of 3D data on the Alto screen. 
(Dick Lyon) 
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♦"♦MISCELLANEOUS PROCEDURES AND INFORMATION*** 
***FOR PARC ALTO USERS 4 ** 



*NEWDISK: a procedure for creating a virgin disk and getting fresh, up-to-date 
software from MAXC. (Bob Sproull) 

*PARCALTOS: a document containing miscellaneous information for Alto users and 
maintainers at PARC. 
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ANSRV, NNSRV - Nova Server 



The purpose of this "system" is to do something like remote job entry to a Nova. There are 
two subsystems involved in this system: NNSRV.sv running on a Nova and ANSRV.run 
running on an Alto. The two subsystems communicate with each other via FTP over the 
Ethernet. ANSRV.run may be found in the <AIto> directory and NNSRV.sv in the 
<RDOS> directory. 

First a user must get NNSRV.sv running on some Nova that is running under the RDOS 03 
operating system and that is connected to the Ethernet. This may be done in the standard 
way, i.e., by typing "NNSRV" to the Nova Command Line Interpreter (CLI). NNSRV 
doesn't use any global or local switches nor take any parameters. NNSRV will start FTP 
(presumably as a server only) and wait for FTP to be "killed" (aborted). Someday there 
may be a Nova server on the Ethernet dedicated to running NNSRV, but until then users 
must start one up themselves. 

In order to use the Nova server, a user should type the following command line to the Alto 
Executive: ANSRV[/s <Nova-host-name>] <Nova-command-line>. 

The "ANSRV" invokes the ANSRV.run subsystem. 

ANSRV accepts one global switch /S. If that switch is not present, then it is assumed that 
the Nova host is named "NovaServer". If the /S is present, then the next token of the Alto 
command line (indicated by "<Nova-host-name>" above) is taken to be a host name. See 
the FTP manual for a discussion of host names. It is supposed to be the Ethernet name of 
the Nova running NNSRV. 

The rest of the Alto command line (indicated by "<Nova-command-line>" above) is taken 
as a Nova command line. In general it is just the same sequence of characters you would 
type to the Nova CLI, but see the documentation for the Alto subsystem ARDOS for details 
because there are some restrictions and inconsistencies with respect to normal Nova 
command lines. 

ANSRV will run FTP to send two files to trie Nova host/server. One of those files 
becomes COM .CM on the Nova and contains a version of what the user typed for <Nova- 
command-line>. Ignore the other file. The Alto FTP also tells the Nova FTP to "kill" 
itself. Then the Alto FTP finishes normally and the user will be talking to the Alto 
Executive again. 

When the Nova FTP is "killed", NNSRV will get control. NNSRV creates any necessary 
files and makes some entries on a log that it maintains on the file $LPT (perhaps the paper 
of an on-line printer). NNSRV then runs the appropriate .SV file. When that .SV file is 
finished, NNSRV" gets control again, makes another entry in the log, and starts up FTP 
again, ready for another go-round. 

There are several things that should be noted about this procedure. NNSRV must be 
running on some Nova when ANSRV is invoked, otherwise the Alto FTP will eventually 
give up trying to establish contact. All the requisite files must be present on the Nova 
when ANSRV is invoked, e.g., the .SV file and any input lies it needs. But note that FTP 
is running on the server Nova most of the time, so a user may use the Alto FTP to transfer 
any necessary files to the Nova before invoking ANSRV. Note that no "answers" are 
automatically sent back to the Alto. The way to take care of this is to have your Nova .SV 
file put its results in a Nova file. Then try to run the Alto FTP to retrieve that file (copy 
it to the Alto). If the Alto FTP can't establish a connection with the Nova FTP, then you 
know that your .SV program (or somebody else's) is still running and you can try again 
later. 
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Now it's time for some examples. We'll assume that NNSRV has been started on a Nova 
named foo. We have a Fortran source code file called FProg.fr on our Mto and we want to 
compile, load, and finally run it. We will give the Alto file fprog.in as input to FPROG.SV 
and tell it to produce tlie file fprog.ot as output. Indented lines below are command lines 
that might be typed to the Alto Executive. 

ftp foo store/c fprog.fr 
ansrv/s foo fort fprog.fr 

Now we'll work on something else on our Alto for awhile and then do: 

ftp foo retrieve/c fprog.er 
type fprog.er 

We'll repeat the above until the file fprog.er comes back with no new compilation errors. If 
there are some eirors, then the source code file muse be edited and the updated fprog.fr sent 
back to the Nova. Now we'll load FProg. 

ansrv/s foo rldr fprog fort.lb 

And wait for the results: 

ftp foo retrieve/c fprog.er 
type fprog.er 

And finally run fprog after it has loaded correctly: 

ftp foo store/c fprog.in 

ansrv/s foo fprog fprog.in/i fprog.ot/o 

Where fprog.in is the input file to fprog and the output file named fprog.ot is to be created 
by fprog.sv. Now we'll wait awhile (or occupy ourselves doing something else) and finally 
examine the results: 

ftp foo retrieve/c fprog.ot 
bravo/n fprog.ot 
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ASM 



This assembler, written in BCPL, runs on the Alto and produces BCPL-compatible 
relocatable binary output files, suitable for input to BLDR, the BCPL, loader. The source 
language of this assembler is patterned after that of the Data General NOVA DOS assembler 
(see document 093-000017-02). Additions, deletions, and incompatibilities are described 
below. 



1. Symbols 

Symbols may be up to 130 characters in length, and every character of a symbol must be 
used to identify it. By default upper- and lower-case characters are different, and two 
character strings represent the same symbol only if the same letters and cases are used in 
both. However, the /U switch causes all lower-case letters in symbols to be changed to 
upper case (even in external symbols). Thus if you want an assembly-language program to 
link to symbols containing lower-case letters, you must either default lower-case conversion 
in ASM or map all symbols to upper case in BLDR using its /U switch. 



2. Strings 

Strings follow BCPL conventions. They may not extend from one line to the next. 

3 . Omitted Pseudo-operations 

The following have been omitted: .TXTO, .TXTE, .TXTF, .XPNG, .IFE, .IFN, .ENDC, and 
.EOT. No f lofting point input format or operators are supported. 

4. Assembly Regions 

This assembler can assemble into three regions: two static regions (one in page 0) and one 
code region. The directives .NREL, .SREL, and .ZREL cause the assembler to begin placing 
code in the code region, the non-page-0 static region, and the page static region, 
respectively. The BCPL loader causes the restrictions that the code area may not contain 
pointers into the code area, that the first word of the code area may not point to a static 
area, and that no static area may contain pointers to a static area. The only external symbols 
are statics. 

Arithmetic is not allowed on symbols denoting statics, and the symbol "." is undefined in 
.SREL and .ZREL.- Any absolute or code-relative expression (including such goodies as 
JMP@ 62) may be placed in .SREL of .ZREL. Any absolute expression, static reference, or 
instruction reference to .ZREL may appear in .NREL. 
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5. Text 

There are two text modes, .TXTM B and .TXTM L. Mode B causes the geneiation of 
star dard BCPL strings. Mode L causes the generation of long strings, a full word length 
followed by the string characters, tv/o per word. 



6. .GET 

The directive .GET "FOO" causes the file FOO to be shoehorned into the source text at that 
poii t. .GET can be used up to two levels deep. Its primary utility is likely to be for lists 
of externals and for canned entry and exit sequences. 



7. .GETNOLIST 

Works exactly like .GET, except that the "gotten" file is no: included in the listing, nor are 
any files which it .GET's. 



8. .BEXT 

In adcition to .EXTN and .EXTD and .ENT, I have added two directives .BEXT and 
.3EXTZ which work exactly as BCPL's External works for norv-page-0 and page statics, 
respectively. This should increase the utility of the .GET feature above. 



9. Expressions 

Parentheses (but not precedence) have been added. Constructs like "K and $*N and 5 and 
17. anc 3B10 are all primaries. Most BCPL and NOVA DOS assembler operators are 
allowed. The construct 1B10 means 40(octal) , following the NOVA assembler's convention 
ather thai BCPL's. I am willing to be convinced on this point. 



10. I/O 



This has been left out. DOA, IOP, .DIO, .DIOA, .DIAC, etc., won't work. 



11. Predefined Symbols 

All predefined symbols and directives and opcodes are defined both in all upper-case and 
all lower-case letters. For example, both LDA and Ida are predefined, but Lda is not. The 
followina Alto-specific opcodes are preloaded in the symbol table: 
JSRII JSRIS CYCLE CONVERT DIR EIR BRI 
RCLK SIO BLT BLKS SIT RDRM WTRM 
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JMPRM MUL DIV 

In addition, the following pile of skips which test various conditions has been added, 
courtesy of Dan Ingalls. Only the names have been changed to confuse the innocent: 
Two operands: 

sze; sz snz sp sgz sn seq 
se sne slt sle sgt sge sgtu 
sleu sgeu sltu sodd skeven snil snnil 
mkzero mkone mknil mkminusone 

No Operands: 

NOP SKIP 

It should be explained :hat U stands for unsigned, and that Dan thinks of NIL as -1. 



12. Operation 

If the source file is called FOO.SR, type 

ASM FOO.SR 

If you just type ASM FOO it will first try to use FOO and, failing in that, try FOO.SR. 

The assembler will usually want to construct several files, which it will do by substituting 

various extensions on FOO unless you specify otherwise. There are a lot of switches which 

apply to ASM: 

/L Construct a listing file 

/S Include the symbols defined by the user, for what they're v/orth 

/A Include all symbols, even the predefined ones 

/R Include a printout of the .BR file 

/N Don't make a .BR file 

/E Make an .ER file which is a copy of the error messages 

sent to the terminal 
/D Print debugging messages (as errors, in fact) 

/P Pause after printing each error message (continue with CR) 

/U Map all lower-case letters in symbols to upper-case 

There are also a lot of switches which apply to file names, and which tell the assembler to 

use this name instead of the one it was aoout to invent: 

/L Names the listing file 

/E Names the error file 

/S Names the source file (also no switches) 

/T Names the temporarv file 

/B Names the relocatabfe binary file 
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Alto Boot Files: Formats and Construction 



The process of "booting" the Alto is one of setting some or all of the Alto's state either by 
reading a file from the disk or by accepting packets from the Ethernet. This document 
attempts to explain the various ways that state is restored, and the formats of "boot files" 
built by various programs. 

There are four basic steps in "booting" the Alto: (1) the tasks in the microprocessor are 
resM; (2) a 256-word "boot loader" is loaded into main memory and started; (3) the boot 
loader loads a portion of Alto main memory from a "boot file" and finishes by transfering 
to a known place; (4) the user's program loaded by the third step can restore even more ot 
the Alto's state. 



1. Booting 

"Booting" is accomplished either by pushing the "boot button" located on the rear of the 
keyboard or by executing the SIO instruction (see Alto Hardware Manual). Unless 
overridden by the Reset Mode Register, the emulator task is started in a standard boot 
program. This program reads location #177034, a word whose contents can be altered by 
pushing various keys on the keyboard. If the <bs> key is depressed during booting, the 
machine state will be restored from the Ethernet; otherwise, the state is restored from the 
disk. 

When booting from the disk, the keyboard word is interpreted as a disk address where a 
"disk boci: loader" is located. If no keys are depressed, disk address is generated, which is 
the normal resting place of the "disJ. boot loader" for the operating system. The emulator 
reads a single 256-word disk record into memory locations 1, 2, ...#400; the 8-word disk 
label for this page is placed in #402, #403, ... #411. When the disk transfer is complete, 
control is transferred to location 1 in the loader. The boot loader uses the saved label to 
point to the remainder of a "boot file" which is read into main memory and started. The 
types of "cisk boot loaders" and "boot files" are discussed below. 

When booting from the Ethernet, the microcode waits until a "breath of life" packet arrives, 
containing a 256-word "Ethernet bcot loader" which is read into locations 1 - #400 and 
executed by transferring t.:> location 3. It is up to this loader to establish communications 
with a party willing to deliver the remainder of the state needed. 



2. Boot File Formats and Boot Loaders 



There are two basic kinds of boot files, and a variant: 

B-File: Built by the Build Boot program; loader is DiskBoot. 

S-File: Built by the OutLd subroutine; "S" loader. 

SO-File: Variant of S-File built by the SaveState subroutine. 

A B-File can be distinguished from an S-File or SO-File because B-Files have a in their 
second data word. 
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B-Files 

B-Files ("BuildBoot" files) are the simplest sort of boot file. The booting process itself does 
not restore the entire state of the machine; page 1 (addresses #400 to #777) is not restored; 
no RAM or R-register state is restored except lor the program counter. 

A boot loader resides in the first (256-word) data page of a B-File. It is this page that is 
read in by the booting process. The file is formatted as follows: 

File page 1 => DiskBoot loader 

File page 2 => Image of memory page (#0-#377) 

File page 3 => Image of memory page 2 (#1000-#1377) 

File page 4 => Image of memory page 3 (#1400-#1777) 

File page n => Image of memory page n-1 

The file can be of any length, except that n must not exceed 254. After reading the entire 
file, control is transferred to the restored state by doing JMP@ 0. 

S- Files 

S-Files ("Swat" files) are a somewhat complicated construction that permits more of the 
Alto state to be restored: the interrupt system, active display, and so forth are all restored. 
In order to achieve this, the restored state must contain a copy of the OutLd subroutine that 
is responsible for the final stage of the restore; when the state is fully restored, this 
subroutine simply returns to its caller. This full state save and restore was originally 
designed for the Swat debugger. (Note: no RAM or R-register state except for the PC and 
accumulators is restored by this kind of boot.) 

A boot loader resides in the first (256-word) data page of an S-File. This is the page read 
by the booting process. The file looks like: 

"S" loader 

Image of memory page 2 (#1000-#1377) 

Image of memory page 3 (#1400-#1777) 

Image of memory page 253 (#176400-#176777) 
Image of memory page 1 (#400-#777) 
Image of memory page (#0-#377) 

The S-File must contain at least 255 data pa^es; additional pages are ignored by the booting 
process, and can be used to save additional state. When the restore is finished, control 
returns to the caller of OutLd (see Alto Operating System Manual). 

SO-Files 

SO-Files are a minor variant of S-Files that can be used lo restore the Alto state in 2 
different ways. The variation is simply that location of the restored memory image (i.e., 
word of file data page 255) contains an "alternate starting address." The file can be loaded 
by (1) using it as an S-File, and executing the loader saved in its first file data page, or (2) 
by a loading process that loads all memory but page 1 (file page 254) and does a JMP@ 0. 
The operating system boot file, Sys.Boot, is an SO- File. 

The SO-File is designed to permit Ethernet booting from states conveniently saved by 
OutLd. 

DiskBoot loader (B-Files) 



File page 1 
File page 2 


=> 
= > 


File page 3 


=> 


File page 253 
File page 254 
File page 255 


=> 
=> 
=> 
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The DiskBoot loader is commonly placed as the first data page in B-Files. Its source is 
DiskBoot.Asm (in BuildBoot.Dm); BuildBoot will normally included this loader on the front 
of the B-Files it constructes. NOTE: the file "DiskBoot.Run" is not a literal copy of the 
256 words that go on the front of the file, but the result of applying BIdr to the relocatable 
file generated by assembling DiskBoot.Asm. 

S loader (S-Files and SO-Files) 

This loader is physically contained within the OutLd subroutine. OutLd simply copies the 
loader onto the first data page of the file on which it saves state. The sources for this 
loader are stored v. ith Operating System sources. 

EtherNet loader ("Breath Of Life") 

The "breath of life" loader, which is periodically broadcast by gateways, is loaded into 
locations l-#400 when the Alto is booted with the <bs> key pressed. The standard form of 
this loader reads location #177035 (a keyboard word), ana transmits "MayDay" packets 
containing the 16-biL result. Some server on the network will interpret the 16-bit argument 
as a request for a specific program. The server will open an EFIT connection with the Alto 
which sent the MayDay. It transmits data pages in the same order as they are recorded in 
B-Files (including the first data page, even though it contains a disk-oriented loader). 
When the connection is closed, the loader does JMP@ 0. 

By convention, I he 16-bit argument #177777 is never answered by a server. This 
convention is used by programs which have specifically started a "breath of life" loader and 
are expecting an EFTP connection from some specific party. 

(More information on Ethernet booting can be found in Ethernet protocols documentation.) 



3. Constructing B-Files: BuildBoot 

Tin program BUILDBOOT.Run will construct files for direct booting into the Alto. The 
program copies its input file into its output file according to directives in the command line 
and in the in tut files themselves. Two kinds of input files are supported at the moment. 
One is the segment file, which contains a block of words to be loaded into contiguous 
addresses. The other is i:he executable file, which is what Bldr produces on the Alto (see 
Alto Operating System Reference Manual for details). If several files in the command line 
specify the contents of the same memory location, the last one will win. In addition to the 
data already in the output file, the program maintains three state variables between items in 
the command line. One is the location counter which specifies the address where the next 
segment file (if any) will be placed. Another is the address where the loaded image is to 
begin execution. This defaults to the starting address of the last executable file in the 
command line. The. third is the address (if any) where the layout vector of the next 
executable file is to be loaded. If this address is missing, the layout vector will not be 
loaded. 

Here are the switches: 

/E This is an executable file (also no switches) 

/S This is a segment file 

/N Reset the location counter to this octal number 

/O This is the output file 

/G This octal number specifies where execution begins 

/B This executable file contains a boot loader in its code 

area. If omitted, defaults to "DiskBoot.Run" 

/L Wiite load map on this file 

/V The layout vector of the next 
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executable file will be loaded in a cont guous 
block starting at the address specified by this 
octal number 

If we wanted to bootify the Nova .SV file PROM.SV, we might say 

BUILDBOOT PROM.BOOT/O PROM.BOOTLIST/L 20/N 1000/Gt 
PROM.SWS 

Similarly, if we had the diagnostic YAMT.Run as an executable file (including any runtime 
support it might need), we could simply say 

BUILDBOOT YAMT.BOOT/O YAMT.BOOTLIST/L YAMT.Run/E 

The disk boot loader DiskBoot.Run is also included in the file BuildBoot.Dm, and is 
required by BuildBoot un ess another boot loader file is specified by the /B switch. 



4. Constructing S-Files: OutLd 

S-Files are constructed by the OulLd subroutine, which is documented in the Alto Operating 
System Manual. 



5. Constructing SO-Files: SaveState 

The SaveState subroutine, also included in BuildBoot.Dm, can be called in a fashion similar 
to OutLd, but it will create an SO-File. The Bcpl call is: 

SaveStatef'filename" [,inits]) 

It l:ehaves like OutLd in that it returns if the file has just been written, 1 if it has been 
restored by an InLcI, and 2 if by a booting process. The optional argument inits controls 
the saving and restoring of critical operating system state (bit table of free pages on the 
disk, open system log information, etc.). The values of inits are: 

0. No OS state saving or restoring is done. 

1. Before saving state, the bit table will be written out and the log closed. 

2. Afte:" restoring state, :he bit table will be read in and the log re-opened. 

3. Functions 1 & 2 are both performed. 



6. The "standard boot file": disk address 

The 256-word clatsi pig; f;ave;l on real disk address cannot be part of any legal Alto file 
because of the way the file system is designed. As a result, the standard boot file is 
established by copying the first data page of the boot file (e.g., Sys.Boot) into disk address 
(the label and data portions are both copied verbatim). Thus the proper data (disk boot 
loader) will be read when booting, and the label will point forward to the (legal) boot file, 
data page 2. 
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CHAT 



CHAT is a program for establishing PUP Telnet connections between a pair of cooperating 
parties, its chief function is to permit Alto users to login to MAXC. Eventual extensions 
will support text-display control. 



1. Simple operation 

CHAT is organized so that default operation with MAXC is simple. Simply saying "CHAT" 
will establish a connection with MAXC and (provided you are "logged in" on your Alto) 
will try to establish the Alto as controlling terminal for a MAXC job that is logged in 
under your name. CHAT will perform a "login" or "attach" as appropriate. If the simple 
methods fail you must deal with MAXC yourself (life is hard). 

Thu preferred method for exiting CHAT is to depress the key immediately to the right of 
the ' return' key on the keyboard, and then to press "q" for Quit. The other method, 
<shift>SWAT. is frowned upon and is r.ot guaranteed to work. 



2. Command Interpreter 

While CHAT is running, you may wish to give various commands that alter its operation. 
Depressing the key immediately to the right of the "return" key will cause CHAT to enter a 
command mode. The commands are: 

Q Quit—terminate the connection. 

F Specify a new font. The screen will be re-initialized, which will cause recent typeout 

to disappear. If insufficient core space is available for the font, the system font will 
be used. 

D Specify a "do" file to insert now. The text of the file will be treated as if it had 

been typed i l at the keyboard—it will be transmitted to the connected party. This is 
a simple way to "can" MAXC procedures that you use a lot. 

E Change local echo setting. CHAT starts out assuming that the connected party will 

echo all characters. In some instances, CHAT will want to echo your typein locally 
(e.g., when connected to another CHAT). 

I Tories the "input" switch for the typescript file, set by the USER.CM entry 

TV Pl-SCRIPTCHARS (see below). 

O Toggles the "output" switch for the typescript file, set by the USER CM entry 



logics tne output switcn toi 
TYPESCRIPTCHArS (see below) 



3. Command-line options 

Several options may be passed to CHAT by global switches in the command line (i.e., by 
typing CHAT/s/t where 's" and "t" are the switches): 
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/A Attach" — meaningful only when connecting to MAXC. This will force the 

MAXC attach sequence to be typed rather than whatever CHAT considers 
appropriate. 

/L "Logi l" -- meaningful only when connecting to MAXC. This forces a login 

sequence to be typed, regardless of what CHAT considers appropriate, hor 
example, if you already have a detached job on MAXC and wish to create a 
new job, you must use this option. 

/N CHAT will not attempt any automatic login or attach for MAXC connections. 

/S CHAT will be a "PUP Telnet Server," and will respond to requests for 

connection from others rather than initiate requests itself. 

/£ CHAT will cause local echoing of input characters. 

/I Equivalent to the command-line entry CHAT.INITIAL/D (see below). 

/P CHAT will enable a display protocol (see below). 

Sevenl options may be specified with "local" switches: 

string This gives the "name" of the party with v/hom CHAT should initiate a 

connection. The name may be an address constant of the form 
net#host^socket, or may be a full symbolic name like Maxc+Telnet (see 
"Naming and Addressing Conventions for Pup" for details). The default 
socket is 1, the Telnet socket. Thus typing "CHAT Regis" will try to connect 
to a Telnet server on the host named Regis. 

filename/F Specifies the name of the font to use. 

filename/D This gives a "do" file name that is fed to the connected party. When the last 
character of the file has been sent, CHAT will not close the connection. 

filename/E Similar to /D, but will end the connection when end of file is encountered. 
(Because of current synchronization problems, this feature will not work well 
in conjunction with MAXC. This problem will be among the first to be 
fixed.) 



4. USER.CM Options 

The USER.CM file may also contain defaults that CHAT examines at initialization. The 
sectio :i of USER.CM that CHAT examines must begin with a line with the 6 characters 
[CHAT] on it. Thereafter, lines begin with "labels," followed immediately by colons, 
followed by arguments: 

FONT: altofontnarne.AL [width height] 

Gives the name of a font to use when displaying typeout from the connected party 
(difiiult: system font). If two numbers follow the name, they are interpreted as the 
width of a line (in characters) and the height of a page (in lines). These numbers 
override the calculations made by CHAT, and are shipped to MAXC to set the 
terminal parameters. 

BORDER: [BLACKJWHITE] 

Gives the color of the top border of the screen (default: white). 
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BELL: [DING] [FLASH] 

Tells what to do when a bell character is received. If DING is specified, a pattern 
that spells out DING will be displayed at the top of the screen. If FLASH is 
specified, the bottom area of the screen will flash black. Both options can be 
specified together (default: DING FLASH). 

CONNECT: net#host#socket or ...network.name... 

Gives the network address constant or name of the party with whom a connection 
should be initiated (see "Naming and Addressing Conventions for PUP" for details). 
Default is Maxc+Telnet, the MAXC PUP Telnet server. 

TYPESCRIPT: filename [length] 

Gives the name of a file on which to record a typescript of the session. The file 
will be treated as a "ring" buffer of specified length (in bytes; default 5120). The 
file will be created at the beginning of the session, so that the user can be certain the 
disk will not overflow when recording typescript information. The string <=> will 
mark the end of the ring buffer, which will be updated periodically. 

TYPESCR1PTCHARS: [ON|OFF] [ON|OFF] 

This entry governs the selection of characters that are included in the typescript file. 
The first on/off switch controls characters typed on the Alto keyboard: if the switch 
is "on," these characters will be entered in the typescript file. The second switch 
controls characters sent from the other party to the Alto: if the switch is "on," these 
characters v/ill be entered in the file. Default is OFF ON. 

LINEFEEDS: [ONIOFF] 

Normally, line feeds transmitted by the other party are included in the typescript 
file, [f you wish to keep line feeds out of the file, set LINEFEEDS: OFF. 

ECHO: [ONIOFF] 

This option turns on local echoing. This is usuclly necessary only if you are 
connecting to another Alto running CHAT that has used the /S option. 

DISPLAYPROTOCOL: [ON|OFF] 

This entry enables a display protocol. This permits the connected party (usually a 
MAXC program) to establish another BSP connection for transmitting a simple 
display protocol to the Alto. A set of INTERLISP-10 functions has been written to 
ease use of the display from LISP. Please see Bob Sproull for more information 
about this protocol and its use. 
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CopyDisk 



CopyDisk is a program for copying entire disk packs. It will copy from one drive to 
another on the same machine, or between drives on separate machines via a network. 



1. History 

The first Alto CopyDisk was called Quick and was written by Gene McDaniel in 1973. 
During the summer of 1975 Graeme Williams wrote a. new CopyDisk adding the ability to 
copy disks over the network. During the summer of 1976 David Boggs redesigned the 
network protocol and added the ability to copy Trident disks. The CopyDisk network 
protocol is specif ie J in <Pup>CopyDisk.ears. 



2. Concepts and Terminology 

In a disk copy :. peration, the information on a 'Source' disk is copied to a 'Destination' 
disk, destroying any previous information on the destination. A copy operation usually 
consists of two steps: 

[Copy] Step one copies bit-for-bii: the information from the source disk to the 
destination disk. 

[Check] Step two reads the destination disk and checks that it is indentical with 
the source disk. This step can be omitted at the user's peril. 

Copying a disk from one machine (or 'host') to another over a network requires the active 
cooperation of programs on both machines. In a typical scenario, a human user invokes a 
program called a 'CopyDisk User' and directs it to establish contact with a 'CopyDisk Server' 
on arother machine. Once contact has been established, the CopyDisk User initiates requests 
and supplies parameters for the actual copy operation which the User and Server carry out 
together. The User and Server roles diner in that the CopyDisk User interacts with a 
human user (usually through some keyboard interpreter) and takes the initiative in 
User/Seiver interactions, whereas the CopyDisk Server plays a comparatively passive role. 
The question of which machine is the CopyDisk User and which is the CopyDisk Server is 
independent of the direction in which data moves. 

The Alto CopyDisk subsystem contains both a CopyDisk User and a CopyDisk Server, 
running as independent processes. Therefore to copy a disk from one machine to another 
you should start up the CopyDisk subsystem on both machines and then type commands to 
one of them, which becomes the CopyDisk User. Subsequent operations are controlled 
entirely from the User end, with no human intervention required at the Server machine. 
Tlv's arrangement is similar to the way the Alto FTP subsystem works, and different from 
I he way the older CopyDisk worked. 



3. Calling CopyDisk 

CopyDisk can be run in two modes: interactive mode in which commands come from the 
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keyboard, and non-interactive mode in which commands come from the command line 
(Com.cm). The general form of the command line to invoke CopyDisk looks like: 

CopyDisk [ [/<option switches>] [from] <source> [to] <destination>] 

The square brackets denote portions of the command line that are optional and may be 
omitted. If you just type "CopyDisk" the program goes into interactive mode, otherwise the 
remainder of the command line must be a complete description of the desired operation. 

3.1. Option Switches 

Each option switch has a default value which is used if the switch is not explicitly set. To 
set a switch to 'false' proceed it with a 'minus' sign (thus CopyDisk/-C means 'no 
checking'). To set a switch to 'true' just mention the switch. 

Switch Default Function 

/4 false [Model44] tells CopyDisk to copy an entire Diablo model 44, without 

asking for confirmation. 

/C true rChecV] tells CopyDisk whether to check the copy operation. 

CopyDisk/-C, which omits the check step, is faster but more risky. 

AV true [WriteProtect] prevents the CopyDisk network Server from writing on 

a local disk. So unless you say CopyDisk/W or issue the 
WRITE: PROTECT commanc, someone can make a copy of your disk 
over the network, but no one can (maliciously or accidentally) 
overwrite it. 

/R true [Ram] tells CopyDisk to attempt to load the ram with some 

microcode which speeds things up considerably. CopyDisk will still 
work, though more slowly if it can't load the ram. 

/D false [Debug] enables extra printout that should be interesting only to 

CopyDisk rnaintainers. 

/B false [Boot] creates 'CopyDisk.boot' for distribution to boot servers. 

/A false [AllocatorDebug] enables extra consistancy checks in the free storage 

allocator. 

3.2. Source and Destination Synta x 

The general form of a. source or destination disk name is: 

[Host name] Device 

for example "[Myrddin]DP0". Ordinarily 'host name' can be a string, e.g., "Myrddin". Most 
Aitos have names which are registered in Name Lookup Servers. So long as a name lookup 
server is available, CopyDisk is able to obtain the information necessary to translate a host 
name to an inter-network address (which is what the underlying network mechanism uses). 
You may omit the host name for disks attached to the local machine. 

If the host name of the Server machine is not known, you may specify an inter-network 
address in its place. The general form of an inter-network address is: 

<network> # <host> # <socket> 
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where each of the three fields is an octal number. The <network> number designates the 
network to which the Server host is connected (which may be different from the one to 
which the User host is i.onnected); this (along with the "#" that follows it) may be omitted 
ir the Server and User are known to be connected to the same network. The <host> number 
designates the Server host's address on <nelwork>. The <socket> number designates the 
actual Server process on that host; ordinarily it should be omitted, since the default is the 
regular CopyDisk server socket. Hence to specify a CopyDisk server running in Alto host 
number 241 on the directly connected network, you should say "241#" (the trailing "#" is 
required). 

The syntax of the 'device' part of a disk name depends on the disk type. CopyDisk 
currently knows how to copy two kinds of disks: 

DPn Diablo disk unit 'n'. Most Altos have one Diablo disk called 

•DPO'. 

TPn Trident disk unit 'n'. The unit number must be in the range 0- 

7. 



4. The CopyDisk display 

CopyDisk displays a title line about one inch from the top of the screen, and below that the 
main display window, which consumes about half of* the screen. The main window is shared 
by the User and Serve* processes, only one of which is active at any time. The process 
which currently owns the window identifies itself at the right side of the title line. The 
title also shows the release dale of the program and the host number of the Alto. When a 
copy operation is in progress, the current disk address is displayed in the area above the 
title line. 

When CopyDisk is started, the User is listening for commands from the keyboard and the 
Server is listening for connections from the network. If you start typing commands, the 
User lakes over control of the main window ('User' appears near the right end of the title 
line), and your commands and their responses are displayed there. The Server refuses 
network connections while the User is active, if another CopyDisk program connects to the 
Server, the Server takes over control of the main window ('Server' appears near the right end 
of the title line), and the Server logs its activity there. The User ignores type-in (flashing 
the screen if any keys are typed) while the Server is active. 



5. Keyboard Command Syntax 

CopyDisk's interactive command interpreter presents a user interface very similar to that of 
the AJto FTP subsystem. The standard editing characters, command recognition features, 
and help facility (via "?") are available. 

5.1. Keyboard Commands 

COPY 

Starts a dialog to gather the information for copying a disk. CopyDisk first asks for 
the name of the source disk by displaying "Copy from". If the disk is local, it makes 
sure it is ready; if the disk is on another machine, it opens a connection and asks the 
remote machine if the disk is ready. If you want to abort the connection attempt, hit 
the middle unmarked ('Chat') key. If the source disk is ready, CopyDisk prompts you 
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for the destination disk by displaying "Copy to", and then checks that that disk is 
ready also. Next, it verifies that the disks are compatible, and depending on the disk 
type, may ask some questions about things peculiar to that disk (such as "Copy all of 
the model 44?"). Then CopyDisk asks you to confirm your intention to overwrite the 
destination disk. If you change your mind, type 'N' or <delete>. If you respond yes, 
CopyDisk will pause for a few seconds, ignoring the keyboard, and then ask you to 
confirm once again. Type-ahead does not work for this second confirmation. This is 
your last chance to look at the disks and make sure that you are not overwriting the 
wrong one. It happens! This feature was in the original CopyDisk, was left out of 
the second version, and is back in this third version by popular demand from the 
many people who made that fatal mistake. 

QUIT 

Terminates CopyDisk. One of three things happens: 

The Alto Exec is restarted if DPO is ready, and has not been written on, 
and if CopyDisk was not booted from the net. 

DPO is booted if it is ready but has been written on or if CopyDisk was 
booted from the net. 

DMT is booted from the net if DPO is not ready. 

All of this is attempting to leave the Alto running something useful. If the disk in 
DPO does not have an operating system on it when CopyDisk quits, the disk boot 
(option 2, above) will fail. This'will not hurt the disk, it will just leave the Alto in a 
bad state. You will have to boot DMT manually. 

CHECK 

Toggles the switch which controls whether a disk is checked after copying. CopyDisk 
displays "on" if checking is now enabled, and "off" if it is now disabled. 

DEBUG 

Toggles the switch which controls the display of debugging information. The 
performance data presented at the end of this document is part of the debugging 
information; the network protocol interactions are displayed when this switch is set 
also. 

WRITEPROTECT 

Toggles the switch which allows the network Server to write on local disks. The 
default is that people can't overwrite your disk. 

VERIFY 

Verifies that two disks are identical. The dialog is very similar to the COPY 
command. Neither disk is ever written. This is useful to verify the health of your 
disk drive (bu: remember that it does not check the write logic). 



6. Command Line Syntax 

CopyDisk can also be controlled from the command line. If there is anything in the 
command line except "CopyDisk" and global switches, the command line interpreter is 
started instead cf the interactive keyboard interpreter. Its operation is most easily explained 
by examples: 
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6.1. Command line examples 

To copy DPO to DPI: 

CopyDisk from DPO to DPI 

Note that 'from' and 'to' are optional (though stongly recommended for clarity), and one or 
both may be omitted or abbreviated: 

CopyDisk DPO t DPI 

is equivalent, though less obvious. 

To copy the Basic non-programmer's disk from host Tape-Controller' (which is running 
CopyDisk) onto a disk in your own machine: 

CopyDisk from [Tape-Controller]DPO to DPO 

or, equivalently: 

CopyDisk from [3'#6'#]DP0 to DPO 

The single quotes are necessary to keep the #s out of the clutches of the Alto Exec. The 
quotes are not needed when typing to the keyboard interpreter. Note that no spaces are 
allowed between the host name and the device name. 

If the command line interpreter runs into trouble, it displays an error message and then 
s tacts the interactive interpreter. 

7. Disk Errors 



Disk errors are termed 'soft' or 'hard' depending on whether retrying the operation corrects 
the difficulty. If CopyDisk is still having trouble after many retries, it displays a message 
of the form "Hard error at DPn: cyl xxx hd y sec zz" in the main window and moves on. 

Soft errors are not reported Unless the debug switch is true, so as not to alarm users. Their 
frequency depends on several factors. Copying over the network will cause more soft errors 
then copying between two disks on the same machine. Alto lis get many more errors then 
Alto Is. 

During the Check pass, in addition to soft and hard errors, 'data compare' errors are also 
possible. A data compare error means that the corresponding sections of the source and 
destination disks are. not identical. If any hard errors have been reported, then data 
compare errors are likely, otherwise getting data compare errors means that something is 
very wrong. You should suspect the Alto. 

Hard errors and data compare errors are serious, and you should not trust the copied pack if 
any are reported. If the errors are on the source disk, try Scavenging it. Bear in mind that 
there is some variance iiii alignment among disk drives, and that a pack which reads fine on 
one drive may have trouble on another. Is the source disk in a different drive than where 
it is normally used? Before allowing the Scavenger to rewrite sectors, consider that the pack 
may be OK, but the drive it is in may be out of alignment. In this case, allowing the 
scavenger to rewrite the sectors is a bad idea. If the errors are on the destination disk, try 
the copy again, and then suspect the pack or the disk drive itself. If the destination pack 
was much colder than the temperature inside the drive, sectors written early in the copy pass 
may read incorrectly during the check pass. It's a good idea to wait a few minutes for the 
pack to reach normal operating temperature before using it. 
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8. Creating a new disk 

Suppose you want to make a new disk by copying one of the 'Basic' disks. There are two 
major ways tu do this: 

Find an Alto with two disk drives. These are relatively rare beasts. This 
method is called the 'double disk copy' method. 

Find two Altos, each with one drive, that are connected by a network. This 
should be relatively easy. This method is called the 'network copy' method. 

Having decided on one of the above methods, you must now get CopyDisk running on the 
A to(s). There are two major ways to do this: 

Start CopyDisk from a disk which has 'CopyDisk. run' on it. 

Boot CopyDisk over the network from a 'Boot Server'. 

8.1. Starting CopyDisk from another Disk 

If you do not hav<2 access to a Boot Server, you must start CopyDisk from a disk that has it 
on it. Put a disk with CopyDisk on it into the Alto and type "CopyDisk<return>". Then 
switch disks. BE CAREFUL!! People sometimes forget to switch disks at this point and 
accidentally copy the wrong one. This is why CopyDisk asks you to confirm your 
intentions so m;ny times. 

8.2. B oo ting Copydisk from the net 

The best way t:> start CopyDisk is to boot it from the network. That way you are more 
likdly to get the latest version, and you avoid the pitfall mentioned above. Of course, you 
must have network access to a Boot Server. Most Gateways have Boot Servers. If this 
method doesn't sfem to work, you will have to fall back to starting CopyDisk from another 
disk. 

Hold down the <BS> and <Quote> keys while pressing the boot button on the Alto. You 
must continue to hold down <BS> and <Quote> (but let go of the boot button!) until a 
small square appears in the middle of the screen. This can take up to 30 seconds, but 
usually happens in less than 5 seconds. You are now taking to the NetExec (see the 
documentation in the Subsystems manual if you are curious), and you should type 
"CopyDisk<return>". The screen will go blank, the little square will appear again (you don't 
have to hold clown any keys this time), and soon CopyDisk should appear on the screen. 

8.3. The Double-Disk Copy Method 

Put the basic disk in DPO and put your disk in DPI. Type "Copy<space>", and when it 
says "from" type DP0<retitrn>. When it says "Copy to", typ^ "DPKreturn>". Then type 
<return> each time it as!;s for confirmation. Some numbers will appear in the top center 
of the screen. When they disappear, CopyDisk is done. Type "Quit<return>". Put the 
basic disk back where it belongs, and take your disk with you. 

8.4. The Network Copy Method 

Unlike the old CopyDisk, you need only type commands to one of the two Altos. It doesn't 
matter which one. Assume i hat the basic disk is in the Alto called "Tape-Controller", your 
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disk is in the Alto called "Myrddin" and you are going to type commands to Tape- 
Controller. Type "Copy<space>", and when it savs "from" type 'DP0< return >". When it 
says "Copy to , type ' [Myrddin]DPO<return>". Then type <return> each time it asks .for 
confirmation. Same numbers will appear in the top center of the screen. When they 
disappear, CopyDisk is done. Type "Quit<return>", and put the basic disk back in the rack. 
Go to Myrddin and type "Quit<return>". It will boot the disk, and you should find 
yourself talking to the Alto Exec. 



9. Performance 



This section calculates the times to copy disks under different conditions. CopyDisk times 
its operations and displays the re 
numbers derived here with reality. 



its operations and displays the results if the debug switch is set, so you can compare the 

ith real i I 



9.1. TSweep 

First, we calculate TSweep, the time to read or write a disk assuming that we can consume 
or produce data faster than the disk. This best possible case is the sum of two terms. The 
first term is the time necessary to sweep an active read/write head over every sector on the 
disk: 

Rot * nCyl * nHds. 

The second term is the time lost while seeking to the next cylinder. We assume that these 
seeks take less than one rotation but that a whole rotation is lost: 

Rot * nCyl. 

Combining, we get: 

TSweep = Rot * nCyl * (nHds+1). 

where: Rot is the rotation time of the disk in seconds 
nCyl is the number of cylinders, and 
nHds is the number of heads. 

9.2. Disk-To-Disk Copy 

By disk-to-disk copy we mean copying from one disk to another on the same machine, 
using a single controller and not overlapping seeks. The fastest way to do this is to read the 
entire source disk into memory, switch to the destination disk, and then write it all. The 
switch from the source to the destination disk, will lose on the average half a revolution 
while waiting for the right sector on the new disk to come under a head. Neglecting the 
switch time which is small compared to the other two terms, the best possible disk-to-disk 
copy time is 2 * TSweep. 

With limited memory, the best we can do is fill all available memory buffers reading the 
source disk, switch disks, write them onto the destination disk, and then switch back to the 
source disk for another load. In this case we can't ignore the switch time, which is the total 
number of sectors on the disk divided by the number of sector buffers times the rotation 
time of the disk: 

Rot * (nCyl * nHds * nSec)/nBuf 

where nSec is tie number of sectors per track, and 
nBuf is the number of memory buffers. 

So the disk-to-disk copy time, TDDCopy, is: 
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TDDCopy = 2 * TSvveep + Rot * (nCyl * nHds * nSec)/nBuf 



9.3. Net Copy 



By net copy we mean copying from a disk on one machine through a network to a disk on 
another machine. In this case the disk controllers can be going in parallel, and the factor 
of tv/o in the first term of TDDCopy vanishes. In additon, if the bandwidth of the 
network connection is higher than the transfer rate of the disks so that as soon as a sector 
is read from the disk it is sent out of the machine, the memory limitation goes away and 
the second term of TDDCopy vanishes. 

The CopyDisk network protocol sends a small amount of information along with each sector 
which must be factored into the calculation of the bandwidth needed to run without 
memory limitation. Note that the bandwidth we are concerned with here is that perceived 
by a client of the network services: user data bits per second, not raw bits per second 
through the network hardware. 

If the network is slower than the disks, then the time to copv a disk is the time required to 
transmit all of the bits on & disk plus the protocol overhead bits: 

TMetCopy = nCyl * nHds * nSec * (sB + sOv)/bwNet 

where sB is the bits of disk information per sector, 

sOv is the CopyDisk protocol overhead per sector, and 
bwNet is the bandwidth of tine network connection. 

The bandwidth of the network connection is hard to state, and depends on a number of 
factors. Here are a few: 

Reduction of the emulator's instruction execution rate due to interference from the 
disk and network hardware. 

Reduction of the amount of the emulator cycles available to the network and disk 
code due to mutual interference. 

Reduction of the peak network bandwith due to interference from other hosts on the 
network. 

The minimum network bandwith required to copy a disk at full speed is: 

MinBwNet = 16 * nCyl * nHds * nSec * (sB + sOv)/TSweep. 

9.4. The Numbers for Altos 
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9.5. Reality 

Here are the results of plugging the numbers into the equations, and comparing them against 
actual measurements. The format is predicted( measured). NA means not available. 



TSweep 

TDDCopy 

TNetCopy 

bwNet 
VlinBwNet 



Diablo-31 

0:24 

0:51(0:51) 

(1:05) 

(323 Kb/s) 
859 Kb/s 



Diablo-44 

0:30 

1:04(1:16) 

(2:16) 

(308 Kb/s) 
1.375 Mb/s 



Trident-80 

1:21 

3:18(4:00) 

(26:31) 

(383 Kb/s) 
7.520 Mb/s 



Trident-300 

4*32 
11:20(19:27) 

(NA) 

8.509 Mb/s 



10. Revision History 

August 7, 1977 

First relese. 

August 28, 1977 

Soft errors are only reported if the debug switch is set. Data compare errors now display 
the offending disk address. VERIFY and WRITEPROTECT commands added to keyboard 
command interpreter. Write protect global switch added. 

October 16, 1977 

More microcode to speed things up 

October 27, 1.977 

Bug fixes 

December 18, 1977 

Fixed a bug which prevented it from copying the second half of a two disk file system. 
The netv/ork format for Diablo disks changed. 

March 22, 1978 



CopyDisk will now do the right thing for TthisHostldevice". The default value of 
WRITEPROTECT is now TRUE. 
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Createfile 



The CREATEFILE subsystem will create a file of a given size, attempting to allocate it 
consecutively on the disk. To run the program, use 

>CREATEFILE filename npages 

where filename is the name of the file and npages is the size of the file in pages (in octal). 
If the file already exists, CREATEFILE will print "Old file — deleted" and delete the file. 
If the file does not exist, CREATEFILE will print "New file". If there is no block of 
npages consecutive free pages on the disk, CREATEFILE will print "Only nnn consecutive 
pages" and create the file at an arbitrary place on the disk; otherwise, CREATEFILE will 
find the smallest block of free pages of size at least npages, and create the file there. 
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DDS - Descriptive Directory System - release 1.13 



The Descriptive Directory System (DDS) is a front end for the Alto file system that 
provides substantially greater flexibility than the "?" facility in the operating system's 
command processor. In addition to file names, the DDS can display file lengths, creation- 
read-write dates, and contents. 

If you have used DDS before and merely wish to learn about changes, bug fixes, and 
new features, you probably want to skip to section 5 of this document. If not, sections 
through 4 are a complete 'description of the current release. Sections significantly changed 
since the last release are marked with ***. 

0. The mouse and cursor 

The three buttons on the mouse are called RED (left or tcp button), YELLOW 
(middle button), and BLUE (right or bottom button). Most mouse-controlled actions in 
DDS happen as soon as you depress the mouse button: these are described below using 
phrases like "RED does xxx", meaning "As soon as you depress RED, xxx happens." Some 
actions require depressing a button and then releasing it: phrases like "clicking RED does 
xxx" mean "If you depress RED and then release it, xxx will happen." Careful reading, or a 
little experimenting, will familiarize you quickly with the distinction. 

The cursor changes shape according to its location on the display and according to 
how DDS is interpreting the buttons. Generally speaking, when the cursor is circular, RED 
selects what you are pointing at in some way, and BLUE deselects it. When the cursor 
assumes the shape of an hourglass, DDS is busy doing something and is not listening to the 
mouse buttons. 

1. The display 

Like Bravo, DDS divides the display into a command area at the top, and one or 
more windows below. Currently DDS just supports a single window. A heavy black bar 
separates the command area from the window. Section 2 (below) describes the command 
area. 

The window has three parts, separated by lighter horizontal bars: 

1) The top part is the view specification area, or viewspec area for short. It contains 
a set of keywords that describe what information is to be displayed for the files being 
examined in this window, and a set of keywords that describe how the displayed files are 
sorted. 

2) The second part is the selection specification area, or selspec area for short. It 
contains a pair of exjDressions which together determine what set of riles is being examined 
in the window. View and selection specification are completely independent: each can be 
changed without affecting the other. 

3) The main part of the window is the data area, which actually displays a set of files. 
The names are always displayed: other information is controlled by the viewspecs. 

1.1 The viewspec area 

There are 10 keywords in the viewspec area that control what is displayed: 
"created" - the date when the file was created 
"written" - the date when the file was last altered 
"read" - the date when the file was last read 

"referenced" - the date when the file was last referenced (i.e. the most recent 
of "created", "written", and "read") 

"size" - the size of the file in disk pages 
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"length" - the length of the file in bytes (characters) 

"address" - the hardware address, in the form directory-pointer: (SN1,SN2)!VN 
@ virtual-leader-address 

"contents" - the contents of the file (in octal, if a binary file) 

"pagemap" - the disk addresses of all pages of the file, with a "*" before each 
address that represents a change of head position 

"leader" - the contents of the file's leader page, in octal 
If the keyword is displayed white-on-black, the corresponding information is displayed in 
the data area, otherwise not. 

There are 6 keywords that control other aspects of how the data are displayed: 

"( marked)" - if turned on, DDS only displays marked files (see sec. 1.4 below) 
"(small)" - if turned on, DDS uses a smaller font for the data, which allows 

more data to appear on the screen (see sec. 3 below for how to tell DDS the name of the 

font) 

"(packed)" - if turned on, DDS displays several files per line if possible (not 

implemented yet) 

"(times)" - in conjunction with "created", "written", "read", or "referenced", 

shows the time of day as well as the date 

"(browse)" - if turned on, then when "contents" is turned on, DDS only 

displays the first 5 lines of text files and the message "*** binary file ***" for binary files, 

instead of the complete contents of the file. 

"(chart)" - if turned on, changes the data display to be a chart made up of 

boxes in which the height of the box is proportional to the tile length. iTry it — you'll 

like it.) 

When the cursor is positioned over a keyword name, RED turns the keyword on; 
BLUE turns the keyword off. When the cursor is over the word "Show:" at the upper left 
of the keywords, BLUE turns alj_key words off. 

There are currently 8 keywords that control sorting of the data: 

"name" - alphabetic order by name (upper and lower case letters are 
equivalent) 

"extension" - alphabetic order by extension 

"created", "written", "read" - the corresponding date and time 

"referenced" - the date last referenced 

"length" - the file length 

"serial" - the file's serial number (not of general interest) 

The keywords which are displayed white-on-black are those actually used to sort the 
data area. They are displayed in the order most- to least-significant criterion, e.g. 
"extension?" followed by ' namet" means sort by extension first, then sort files with the 
same extension by name. Following each keyword, whether active or not, is an arrow which 
indicates whether the sort is to be in ascending (upward arrow) or descending (downward 
arrow). 

When the cursor is positioned over a sorting keyword name, clicking RED turns the 
keyword on and adds it to the list of white-on-black keywords actually used for sorting; 
clicking BLUE turns the keyword off and removes it from the list; clicking YELLOW 
inverts the direction of the arrow, regardless of whether the keyword is in the list. When 
the cursor is over the words "Sort by:' at the left of the sorting keywords, BLUE turns off 
a]]_sorting criteria. 



Since sorting may take a long time and it is easy to request sorting by accident, you 
can abort sorting at any time by typing any character. Be sure the cursor is not in the data 
area when you do this: if it is, DDS may start the sort over again! 



Whenever the cursor moves into the data area, regardless of whether any mouse 
buttons are down, DDS repaints the display to be as specified by the viewspecs if the 
viewspecs have changed since the last time the display was repainted. 
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1.2 The selspec area 

The selspec area contains two expressions which defines what subset of the directory 
will actually be displayed in the data area. These expressions are built up from name 
patterns which are similar to those recognized by the Alto Executive. More precisely, a 
name pattern is a sequence of characters which may contain "*"s and "#"s: "*" matches any 
sequence of characters in a name (including no characters at all), "#" matches any single 
character. Upper and lower case letters are not distinguished. Note that DDS deletes the 
final "." from file names. Here are some examples of name patterns and what they match: 

*.BC All files with extension BC (or be, bC, or Be). 

*.B All files with extension B. 

*.B* All files whose names contain the string .B -- this includes all files with 
extension Bsomething, but also includes files like THIS.BINARY.THAT. 

*.B# All files whose extensions consist of B and one more character. 

* All the files in the directory. 

You can build up more complex expressions using the words "and", "or", and "not", 
and parentheses. Here are some examples of such expressions and what they select: 
LPD* and not *.temp 

All files beginning with LPD, except those with extension temp. 
*.memo or *.memo$ 

All files with extension memo or memo$. 
(*.BT or *.BS) and not X* 

All files with extension BT or BS, except those beginning with X. 

The upper expression in the selspec area is called the selspec; the lower one is called 
the context. (The two together are simply called the selspecs.) Only files which satisfy both 
expressions will be displayed. The idea is that if you are going to be working on memos, 
for example, you can set the context to "*.memo" and use the selspec to further select within 
this set. As another example, if there is some set of files you want not to see (like "*$"), 
you can set the context to 'not *$". 

To change the selspec or the context, point at it, or at the word "Selspec:" or 
"Context:", and click RED or YELLOW. This will cause it to change to white-on-black. 
As soon as you start typing, the old text will vanish and what you type will appear white- 
on-black in its place. Eventually you must type one of the following three things before 
you can point anywhere else or select any commands (see sec. 2 below): 

< return > confirms the change, and repaints the display to reflect it. 

<esc> is equivalent to *<return>, i.e. it adds a * to what you have typed and then 
confirms the change. 

<del> aborts the typein and restores the old selspec or context expression. 

See section 3 below for how to get the selspec and/or context initialized 
automatically to something other than "*" when you first enter DDS. 

The third line of the selspec area is a message of the form "nnn files are selected, of 
which mmm are marked" where nnn is the count ot files selected by the current selspec and 
mmm is the count of those which are marked (see 1.4 below). If there are marked files not 
selected by the selspec (again, see 1.4), the message "there are kkk files marked but not 
selected" also appears. While DDS is sorting data, the message "Sorting ..." appears in this 
area in place of the file counts. 

1.3 The data area 

As mentioned above, whenever the cursor moves into the data area, DDS regenerates 
the display if necessary to conform to the current viewspecs. 

The left edge of the data area is a scrolling bar which works the same way as in 
Bravo: clicking RED scrolls up, clicking BLUE scrolls down, and clicking YELLOW jumps 
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proportionately to the vertical location in the v/indow. A hollow arrow in the left margin 
shows where in the list you are positioned: if the arrow is at the top, you are at the 
beginning of the list; if the arrow is at the bottom, you are at the end. The idea is that if 
you were to move the cursor to this arrow and click YELLOW, the list would stay 
positioned just as it is. (This feature may appear in Bravo some day too.) 

If you are positioned at the beginning of the list of selected files, DDS displays the 

message " BEGIN " at the head of the list; if not, DDS displays " nnn 

files not shown ", indicating the position within the list of the first file actually 

shown on the screen (e.g. "2 files not shown" means the first file on the screen is actually 
the third in the list). Similarly, if the last file shown on the screen is actually the last file 
in the list, DDS displays " ~~ END " below it. 

A vertical strip at the right edge of the data area will be used in the future to 
control the formatting of the screen into windows. Currently the cursor changes shape when 
it is in this area, but the buttons have no effect. Another vertical strip just to the left of 
this one is used for mass marking and unmarking of files: see the following section. 

1.4 Marking files 

DDS provides a facility for marking any set of files for later processing bv 
commands such as <Delete>, <Send to Maxc>, etc. Marked files are displayed with a small 
dark arrow in the left margin, and a count of how many marked files are in the current 
selected set is maintained in the selspec window. When the cursor is in the data area of a 
window, other than the right or left edge areas, the mouse buttons control marking and 
unmarking of individual files: RED marks the file on whose line the cursor resides; BLUE 
unmarks the file. When the cursor is in the vertical strip about 1" in from the right edge 
of the screen, the cursor changes to the word "ALL", and the buttons mark and unmark files 
en masse: clicking RED marks all the files selected by the selspecs; clicking BLUE unmarks 
all the files. 

Note that files may be marked even though they are not selected by the current 
selspecs, i.e. marking is associated with the file rather than the display. (If this proves 
confusing it will be changed.) The count of "files marked but not selected" in the selspec 
area lets you know when there are marked files not selected by the current selspecs. 

Since marking or unmarking individual files occurs as soon as the button is 
depressed, you can hold dowr. RED or BLUE and slide the mouse (slowly) in the vertical 
direction to mark or unmark a group of adjacent files. 

The marked file counts in the selspec window are adjusted as soon as a file is 
marked or unmarked, but if the "marked" viewspec is on and you unmark a file, you must 
scroll the data to get the unmarked file(s) deleted from the display. 

2. Commands 

The command area at the top of the screen consists of four parts: 

1) A header with the DDS version number, time of day, and count of free disk pages; 

2) A type-in area, where typed characters appear; 
4) An error message line; 

3) A menu of commands, with each built-in command being enclosed in angle 
brackets <>. 

When the mouse is in the command menu area, RED selects a command for 
subsequent execution: the selected command is displayed white-on-black, and any previously 
selected command is deselected. BLUE deselects the currently selected command and selects 
the default command <Quit>. Typing <esc> or <return> finally initiates the command: you 
can freely select or deselect commands, type and edit your type-in, change viewspecs, etc. up 
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to that moment. For commands which do not require type-in, you may also initiate the 
command by clicking YELLOW with the mouse in the command menu area. The cursor 
takes the shape of a circle with a cross when this is allowed, and a circle with a dot when it 
is not. 

Some commands require or allow type-in before the final <esc> or <return>. You 
may type at any time. All typed characters are accumulated in the type-in area just below 
the header until the <esc> or <return>. Control-A (or backspace), control-W, control-Q, 
and <del> are available for editing as in Bravo. DDS displays a vertical bar when it is 
waiting for your typing, and of course you can "t>pe ahead" while DDS is processing a 
command. However, as for selspec and context changes (sec. 1.2), once you have started to 
type, you must either confirm the command with <esc> or <return>, or abort with <del>, 
before you can select another command or another place to type (selspec or context). 

When you have selected a command with RED, then when you release the button, 
DDS may display something in the type-in area which is a default for that command. If 
you want to execute the command with that default type-in, you can just confirm it (with 
<esc>, <return>, or YELLOW); otherwise, the default disappears as soon as you start typing, 
just like the old selspec or context. 

In the description of commands below, "something" following the command name 
means that DDS expects you to have typed something before the final <esc> or <return> 
that initiates the command; "optional-something" means you may type something or not. 
To help you remember, all the commands that require type-in end with "...", and those 
which allow but do not require type-in end with "[...]". 

Many commands operate on a set of files: they use precisely those files which, at the 
time you type the final <esc> or < return >, are both selected (i.e. match the selspec) and 
marked, "Filename- 1 ... filename-n" in the descriptions below refer to these files, which are 
also called the "designated" files. 

DDS presently has tv/o classes of command:.: those which leave you in DDS after 
execution (internal commands), and those which send you back to the Alto Executive 
(external commands). DDS has a fixed collection of ir.ternal commands, but you can add 
new external commands of your ov/n: see section 3 below for how to do this. For external 
commands, DDS saves away a command line so that if something goes wrong, you can 
execute the command again by typing @DDS.CM@<ieturn> to the Executive. 

2.1 Internal commands (those which leave you in DDS) 

<Put on file ...> "filename" writes on the file named "filename" (in text form) the 
contents of the window. DDS also writes a header with your name, the disk name, and the 
date and time. The default for "filename" is "Dir.Lst", an arbitrary name which DDS 
supplies so that you don't have to make one up. 

<List on file ...> "filename" writes on the file named "filename" (in text form) the 
names of the designated files, separated by blanks. This makes it easy for you to make up 
an @-file for the Executive by adding a command name to the front of this file. The 
default for "filename" is "Dir.Cm", an arbitrary name which DDS supplies so you don't 
have to make one up. 

<Delete> deletes the designated files. There is presently no way to un-delete files, so 
be careful: the count of marked 'files in the selspec window is a good clue as to whether you 
are deleting more than you want. You can stop a <Delete> at any time by typing any 
character: of course, some files may already have been deleted. DDS changes the "free 
pages" count at the top of the screen as it deletes each file. 

<Rename as ...> "filename" requires that there be exactly one designated file, and 
changes its name to "filename". If there is already a file named "filename", <Rename> 
gives an error message and does nothing else. 
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< Initialize [select ...]> "selspec" restores your selspec, context, and vievvspecs to what 
you have specified in User.Cm. Ir you typed something, DDS takes that in place of the 
selspec in User.Cm. 

2.2 External commands (those which leave you in the Executive) 

<Quit> leaves DDS gracefully. Shift-Swat is also safe whenever DDS is awaiting 
input (i.e. not in the midst of sorting, deleting, etc.). 

<Bravo/[...]> "optional-switches" gives control to Bravo in the following way: 

If there are no designated files, DDS effectively executes "Bravo/switches'. 

If there is more than one designated file, DDS gives an error message and does 
nothing else. 

If there is a single designated file and you did not type anything, DDS effectively 
executes "Bravo/N filename", i.e. instructs Bravo to read in the file. 

If there is a single designated file and you did type in sv/itches, DDS executes 
"Bravo/switches filename". 

<Gears/[...]> "optional-switches" executes "Gears/switches filename-1 ... filename-n", 
i.e. prints the designatea files. 

<Send to Maxc directory <...>> "directory-name" sends the designated files to the 
directory named "directory-name" on Maxc, using Ftp. The default for directory-name is 
the user name on your Alto disk. If you accept the default, DDS assumes you have already 
done a Login in the Executive to supply the password; if you supply some other directory- 
name XYZ, DDS arranges things so the Executive will prompt you with the message "File 
XYZ-Password does not exist, type what it would contain" and you should type in the 
password for XYZ at that time. 

<Send to .„> "name" se:ids the designated files to the Alto whose name is "name", 
using Ftp. "Name" may be anything acceptable to Ftp. i.e. an Alto name, an Alto number, 
etc. The default for "name" is Maxc, which is not really very useful. 

< Execute ...> "command" constructs a command line formed from "command" and 
the names of the designated files, and then executes the command line thus formed by 
either jumping directly to the subsystem or returning to the Alto Executive. (If there are no 
designated files, DDS produces an error message "No files are marked" and does nothing 
else.) The command line is formed in the following way: 

If "command' does not contain any "*" characters, the command line is just 
"command" followed by the names of the designated files. For example, if files ALPHA 
and BETA are designated, < Execute ...> "BLDR/L" would execute the command line 
"BLDR/L ALPHA BETA" "String" may contain blanks, so for example <Execute> "BLDR 
FOO/S" would execute "BLDR FOO/S ALPHA BETA". 

If "command" does contain a "*", DDS divides "command" into 3 parts "si s2*s3", 
where s2 is the part of "command" extending backwards from the "*" to the first preceding 
blank (or the beginning of "command"). Then the command line is "sL s2fls3 s2f2s3 
where fl, f2, etc. are the names of the files. For example, if ALPHA and BETA are 
designated, < Execute ...> "BLDR @*@" would execute the command line "BLDR 
@ ALPHA® @BETA@". (If this seems confusing or useless, don't worry about it too much 
-- some future version of DDS may find a better way to provide this facility.) 

2.3 User-defined commands 

If you define your own external commands with a SUBSYSTEMS entry in User.Cm 
as described in section 3 below, these commands will also appear in the command menu 
along with all the com ma ids listed just above. They behave exactly like the <Execute> 
command with respect to what they do about *'s, tyr.ein, and designated files. For example, 
suppose your SUBSYSTEMS list looks like this: 
SUBSYSTEMS: Chat, Ftp/-S Maxc, Foo 
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Then if you select the second command with files Alpha and Beta designated and type 
Dump/C Blap.DM, what will actually get executed is Ftp/-S Maxc Dump/C Blap.DM Alpha 
Beta. 

2.4 Error messages 

Nor-fatal error messages appear in bold characters just below the type-in line. Such 
messages always abort the current command and reset the command to <Quit>, but they do 
not change the state of DDS in any other way. The message disappears as soon as you type 
any character. 

Fatal errors cause DDS to call Swat. When this happens, the screen changes 
completely and a heading like "Swat.21 (August 28, 1976)" appears at the top; the error 
message itself appears at the bottom of the screen just above a ' #". Fatal errors are never 
supposed to happen, but if one ever does, summon a DDS expert. If none is available, write 
down the message and what you were doing at the time, and then type control-K. This will 
throw you out of DDS and back to the Executive. 

3. User profile 

DDS examines the user profile (User.Cm) during initialization to obtain the names 
of the fonts which v/ill be used to display various things, and other rarely-changed 
information. Just as Bravo's section of User.Cm becins with [BRAVO] and then follows 
the format of OPTION:STRING, DDS looks for [DD^ and follows the same format for its 
entries. 

The entries which DDS recognizes in User.Cm fall into two classes. "Initialization- 
only" entries are those which DDS only consults when you ask it to do a full initialization 
(by using the FULLINIT: Yes entry in User.Cm, or the /I switch in the command line, both 
described below). "Ordinary" entries are those which DDS looks at every time. 

The rames of the "ordinary" entries are: 

FONT: fontname - specifies the name of the normal font (used for the command 
window, the file count line, and the data area). 

BOLDFONT: fontname - specifies the name of the bold font (used for error messages, 
the viewspec and selspec display, and the headings on the data area). 

SMALLFONT: fontname - specifies the name of the small font (used for displaying 
data when the "(small)" viewspec is turned on). 

SMALL BOLDFONT: fontname - specifies the name of the small bold font. 

USERTYPE: type - lets DDS know what kind of user you are. If type is NON- 
PROGRAMMER, DDS doesn't provide the "pagemap" and "address" viewspecs. If type is 
WIZARD, DDS provides some extra features for debugging which are not described in this 
document. 

WINDOWS: Yes - enables you to use some experimental facilities for splitting the 
screen into multiple windows in a Bravo-like manner. These facilities are NOT 
DOCUMENTED, NOT FULLY DEBUGGED, AND NOT RECOMMENDED. 

RAMOK: Yes - tells DDS to use the RAM on your Alto. If your Alto is a standard 
one, this v/ill make DDS run about 30% faster; if not, DDS may not run faster, and mav 
not run at all. Try it once (or use the /R switch in the command line as described below) 
and see what happens. 

FULLINIT: Yes - tells DDS to scan the whole Alto file directory each time it starts 
up, and reinitialize the sdspec, context, etc. from the "initialization-only" entries, in User.Cm 
(possibly overridden by the command line: see sec. 4). FULLINIT: No - tells DDS to 
updcte its knowledge of the world from Sys.Log (an incremental record of file activity since 
you last ran DDS), and restore the selspec, context, etc. to what they wers when you last left 
DDS. The default is FULLINIT: No which leads to much faster startup. BECAUSE OF 
DEFICIENCIES IN THE ALTO OS AND IN BRAVO, THE RELEASED VERSION OF 
DDS FORCES FULLINIT: YES REGARDLESS OF WHAT IS IN USER.CM. 
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REENTER: Yes - tells DDS that you want to go back to DDS after completion of an 
external command. (Normally the Executive retains control after an external command 
finishes.) 

The names of the "initialization-only" entries are: 

SELSPEC: expression - specifies the initial value of the selspec when you enter DDS. 
If there is something illecal about the expression, DDS just uses "*' for the initial selspec, as 
though there were no SELSPEC entry in User.Cm. 

CONTEXT: expression - specifies the initial value of the context when you enter DDS. 

SHOW: list of viewspecs - allows you to initialize the viewspecs. Use commas between 
viewspecs if there is more than one. 

SORT BY: list of sorting keywords - allows you to initialize the sorting order. Each 
keyword may be followed by "t" for ascending order or "<-" for descending order (neither 
means £scending order). Use commas between keywords if there is more than one. 

SUBSYSTEMS: list of commands - allows you to add your own favorite subsystems to 
DDS' command set. Each command may be just a subsystem name (e.g. Chat) or a 
subsystem name followed by some initial arguments (e.g. Ftp/-S Maxc Dump/C). Use 
commas between entries if there is more than one. 

A word about fonts: if FONT is not specified in User.Cm, DDS uses the standard 
system font SysFont.Al. If BOLDFONT is not specified, DDS fabricates a boldface version 
of the normal font, whatever it may be. If SMALLFONT is not specified, the "(small)" 
viewspec has no effect. If you specify a font name and there is no file by that name, DDS 
just ignores that entry in User.Cm. 

4. The command line 

Just typing DDS to the Alto Executive will activate DDS in its normal way, in 
which various aspects of its behavior are controlled by entries in User.Cm if present. 
However, you can override User.Cm by typing switches following the name DDS to the 
Executive. Here are the switches currently implemented: 

DDS/E - equivalent to REENTER: Yes in User.Cm. 

DDS/-E - overrides (cancels) REENTER: Yes in User.Cm. 

DDS/I - equivalent to FULLINIT: Yes in User.Cm. 

DDS/- 1 •• overrides (cancels) FULLINIT: Yes in User.Cm. 

DDS/R - equivalent to RAMOK: Ye; in User.Cm. 

DDS/-R - overrides (cancels) RAMOK: Yes in User.Cm. 

DDS/W - equivalent to WINDOWS: Yes in User.Cm. 

DDS/-W - overrides (cancels) WINDOWS: Yes in User.Cm. 

DDS/S - causes DDS to write some statistics in a file DDS.STATS. Not currently of 
general inteiest. 

DDS/P - causes DDS to write some data regarding disk activity in DDS.STATS. Not 
of general interest. 

DDS/X - causes DDS to display some mysterious statistics at the top of the screen. 
Not of general interest. 

These switches can be combined, e.g. DDS/I/R causes both full initialization and use of the 
RAM. Switches may be either upper or lower case. 

If DDS is doing a full initialization (either because FULLINIT: Yes appears in 
User.Cm or because you said DDS/I), you ma> also supply initial selspec and context strings 
in the command line, and these will take precedence over those in User.Cm, if any. 
Unfortunately, the Alto Executive makes it a little inconvenient to include *'s in these 
strings, and you can't have blanks in them at all. To include a *, you must type '*, e.g. to 
start up DDS and specify alpha* as the selspec, you must type 

DDS/I alpha'* 
to the Executive. To specify beta* as the selspec and *.cm as the context, you must type 

DDS/I bota'* '*.cm 
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5. Record of bug fixes, changes, and enhancements 

Release 1.13: 

Bugs fixed: user-defined commands were usually ignored even on full ink. 

Additions: REENTER in User.Cm (sec. 3); /E in command line (sec. 4). 
Release 1.12: 

Bugs fixed: crash if User.Cmln existed but no User.Cm. 

Changes: fast startup permanently disabled. 

Additions: "leader" viewspec (sec. 1.1); <List> and <Initialize> commands (sec. 2.1); 
user-defined commands (sec. 2.3, 3); /X in command line (sec. 4). 

Release 1.11: 

Bugs fixed: falling into Swat when running on non-standard Alto configurations; fast 
startup now works. 

Changes: can point at "Selspec:" and "Context:" (sec. 1.2); feedback after deleting each 
file (sec. 2.1); user and disk name appear on <Put> file (sec. 2.1); fast startup is the default 
(sec. 3). 

Additions: WINDOWS and RAMOK in User.Cm (sec. 3); switches, initial selspec and 
context in command line (sec. 4). 

Release 1.10: 

Bugs fixed: "Bad YP" and "Bad tree" from <Delete>. 

Changes: runs only under Alto OS version 5 or later; typing in selspec directly (sec. 
1.2), "All" strip for marking/unmarking all files (sec. 1.3, 1.4). new typein scheme for 
commands (sec. 2); change in <Send> commands (sec. 2.1). 

Additions: "(chart)" viewspec for pictorial file lengths (sec. 1.1); BEGIN, END, arrow 
for clearer indication of position within data list (sec. 1.3); default typein for commands 
(sec. 2); saving command line in DDS.CM (sec. 2); initializing viewspecs and sorting from 
User.Cm (sec. 3); fast startup feature (sec. 3). 

Release 1.9: 

*** There was no official release 1.9. 

Release 1.8: 

Bugs fixed: stack overflows (really!), "Vstream error" after <Delete>; file name from 
<Put> wasn't getting added to data base. 

Changes: runs under new Alto Operating System; "contents" viewspec shows the whole 
file (sec. 1.1); marking all files is now done in selspec area (sec. L.4); error message line 
moved to just below type-in line (sec. 2). 

Enhancements: "referenced", "(browse)", and "(small)" viewspecs (sec. 1.1); 
interrupting sorting by typing (sec. 1.1); context expression (sec. 1.2); initiating commands 
with YELLOW in command menu (sec. 2); <Context> and <Kename> commands (sec. 2.1); 
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interrupting <Delete> by typing (sec. 2.1); SMALLFONT, SMALLBOLDFONT, SELSPEC, 
CONTEXT, USERTYPE options in User.Cm (sec. 3). 

Release 1.7: 

Bugs fixed: "Break at 0" or "Break at 1" during <Delete>; occasional stack overflows 
("Break at getframe+36"). 

Changes: error messages now appear in their own area (sec. 2.2); cursor need not be 
in the window when confirming a command (sec. 2). 

Enhancements: documentation sec. 2 has been expanded and improved to clarify the 
notion of designated files. 

Release 1.6: 

Bugs fixed: DDS would go into SWAT "Break at getframe+36" (stack overflows); also 
occasional "Bad vp" or "Vstream error" messages. A couple of typos in the documentation 
also fixed. 

Enhancements: blinking caret for type-in (sec. 2); complex selspec expressions (sec. 
1.2); count of marked files not selected (sec. 1.2, 1.4). 

Release 1.5: 

Changes: command menu in place of control characters (sec. 2); viewspecs do not 
require clicking (sec. 1.1). 

Enhancements: Delete, Send, Bravo, Gears commands are built in (sec. 2); sorting by 
serial # (sec. 1.2). 

Release 1.4: 

Changes: date-and-time line rearranged; better behavior when displayed properties do 
not fit on one line. 

Enhancements: "Sorting ..." message (sec. 1.2); "*" feature in t Execute (sec. 2). 

Release 1.3: 

Bugs fixed: system would blow up on any attempt to produce an error message such 
as "Mouse is not in a window"; system would sometimes blow up when starting up; the date- 
and-time line no longer blinks. 

Changes: 1 Execute now only. processes marked files (sec. 1.4, 2); sorting by extension 
is implemented (sec. 1.1). 

Enhancements: marking individual files (sec. 1.4); displaying the file count (sec. 1.2, 
1.4); "pagemap" viewspec (sec. 1.1); user-selectable fonts (sec. z.l). 
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DMT, Peek, PeekSum 



This documentation describes the operation of three related Alto Subsystems: DMT, the 
Memory/Control Ram diagnostic; Peek, the program to which DMT reports its findings; and 
PeekSum, the program which summarizes the reports collected by Peek. 



1. Creating; a Peek Disk 

You should devote a separate disk to Peek -- it has special requirements. If the Peek disk 
isn't cleaned out regularly, you will find the Peeking Alto in Swat out of disk space after a 
long holiday weekend, especially if your network has many machines. Peek is also a boot 
server (see below for details), so it is important that the boot files on the Peek disk be 
current. The easiest way to meet both of these requirements is to periodically recreate the 
Peek disk from scratch: 

1) Boot an OS from the net and respond 'Yes' when it asks if you want the long 
installation dialog, and 'Yes' when it asks if you want to ERASE the disk. 

2) Retrieve <AIto>PeekDisk.cm and invoke it by typing to the Exec: 

>@PeekDisk.cm@ 



2. History 

Chuck Thacker made DMT (early 1973) by combining many small diagnostics which he had 
developed to stress main memory using certain emulator instructions. "There were originally 
two versions: PMT (Printer Memory Test) which logged statistics on the Diablo printer; and 
DMT (Display Memory Test) which used the display. Later (late 1973), an Ethernet driver 
was added to DMT, Bob Metcalfe wrote Peek, and Chuck wrote PeekSum. At this point, 
development and maintenance of PMT stopped. Still later (mid 1975), Dave Bcggs added a 
Control Ram tesi: to DMT, rewrote the Ethernet driver and took over maintenance. Nate 
Tobol wrote the Alto II memory test (mid 1976), which was merged into DMT. Dave 
rewrote Peek and took over its maintenance. Doug Claik extended PeekSum, and took over 
its maintenance (early 1977). 



3. DMT 

DMT is written in the BCPL-compatible variant of Nova Machine language and distributed 
as a type~B boot file (see the BuilclBoot documentation for more details). 

When DMT is runniig, the Alto screen is black with a white cursor changing position once 
each time through [he main loop. For Alto I the cursor flips at random intervals; for Alto 
II i he interval is about 1 second. On Alto lis with extended memory, the cursor contains a 
number between and 3 indicating which bank it is currently testing. Two keys are 
checked each time through the main loop. 
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3.1. Statistics 

If the 'S' key is depressed, DMT will display (and transmit on the Ethernet) the statistics it 
has accumulated. The display looks something like this: 

DMT of 10 Dec 77, Alto II XM 241. 456 blocks, testing 17341 to 176777 
bad main memory chips 
bad control memory chips 

If there are errors, a line describing each type of error will be displayed, and then, if the 
errors can be resolved to a particular chip, the Card, Row and Column (for Alto I), or the 
Card and Chip number (for Alto II) will be displayed. This display will stay up as long as 
the S key is depressed. Periodically the statistics are automatically broadcast on the Ethernet 
and appear briefly on the screen. 

3.2. Super Simple Debugger - SSD 

If the 'Q' key is depressed, DMT will enter SSD, an octal debugger. The screen will change 
to white background, and 3 rows of numbers will appear. 

The top row of numbers are the emulator state when the debugger got control: ACO, AC1, 
AC2, AC3, Carry, and PC. There are two ways to enter the debugger: by executing some 
flavor of JSR whose effective address is the debugger entry point, in which case PC will be 
zero; or by executing an unimplemented op-code, in which case PC will contain TRAPPC 
(location '"27). The most common way for a Nova program to die is to jump to some small 
address, so DMT sets up low core to call the debugger. A less likely way to die, but useful 
for setting breakpoints, is to execute an unimplementec. op-code, so DMT sets up the 
Trap Vector in page 1 to call the debugger also. 

The middle row of numbers are the the R-registers from the last parity error: DCBR, 
KNMAR, DWA, CBA, PC, and SAD. These locations are written by the parity task 
microcode and read by diagno:tic programs when analyzing a parity error. 

The bottom row displays two internal debugger registers, User Value (UVO) and User 
Value 1 (UV1). UV1 is displayed only if SSD has opened a main memory location. 

SSD recognizes the commands listed below. C(UVO) means contents of the memory location 
addressed by UVO. 'OpenCell' is true if UV1 is being displayed. Type-in goes into UVO if 
no cell is open, otherwise it goes into UV1. 

/ if OpenCell then UVO «- UV1; UV1 «- c(UVO); OpenCell *• true 

cr if OpenCell then c(UVO) «• UV1; OpenCell <- false 

del OpenCell <- false 

bs if OpenCell then c(UVl) <- c(UVl) rshift 3 

If if OpenCell then c(UVO) <- UV1; UVO <- UV0+1; UV1 <- c(UVO); 
OpenCell «- true 

t if OpenCell then c(UVO) <- UV1; UVO «• UV0-1; UV1 <~ c(UVO); 
OpenCell «- true 

G Restore SUite; Goto UVO 

P Restore state; Goto (PC eq ? AC3, PC) 



4. Peek 

Peek currently conditions the Ethernet interface to masquerade as host #376, ignoring the 
normal Alto host address. This way peek can run on any machine and DMT does not have 
to find it. This will eventually be changed when DMT implements the Pup Resource 
Location Protocol. 
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Peek opens several windows on the display. The top window is for user commands. There 
is current y only one: Quit. The next window displays the release date of the program, a 
digits 1 clock, the Pup internetwork address o; the machine, and the number of free pages on 
the disk. The next window is opened by the Peek Server and displays DMT reports as they 
arrive. 

Peek has a number of options, and reads User.cm to find out what to do. An example of 
the Peek slice of a User.cm file is given below. 

4.1. Peek Server 

If there is a line of the form "Peek: <filename>" in User.cm, Peek will start up a Peeking 
process which will listen for raw Ether packets of type PeekReport and write them on 
<filename>. The filename should be 'Peek.reports' since PeekSum, described below, assumes 
this. 

4.2. Event Report Server 

Peek implements the Pup Event Report protocol. For each line of the form "ERP: 
<!number> ■ Cfilename>" in User.cm, Peek will instantiate an event report process which will 
listen on socket <number> and write event reports on <filename>. 

4.3. Boot File Server 

Peek implements the protocols necessary to be an Alto boot file server. For each line of the 
form "Boot: <number) <filename>" in User.cm, Peek will send <filename> when it receives 
a Mayday packet requesting bootfile <number>. 

4.4. Raw Ether Echo Server 

Peek implements the raw Ethernet Echo protocol. This is the echo protocol used by EDP 
and NEDP, the diagnostic programs for the Alto and Nova Ethernet interfaces. As 
mentioned above, the host address is #376. 

4.5. Network Directory Maintenance 

PeekSum uses the network directory, which is available from Name-Lookup servers on the 
network as a file called 'Pup-Network.Directory'. Peek implements a subset of the network 
update protocol to keep the local copy up-to-date. 

4.6. User.cm Example 

Below is an example of the Peek part of a User.cm file. In this example DMT statistics go 
to the file 'Peek.reports', Event reports addressed to socket 30 (swat parity error reports) go 
to the file 'Swat.ERP', and three maintenance-type boot files are available for diagnosing 
Altos. Notice that all characters between a semicolon and a carriage return are considered 
to be comments arid ignored by Peek (this is not true for all programs that use User.cm). 

[EXECUTIVE] 
...executive stuff... 

CPEEK] 
; Syntax: 
; Boot <bootFileNumber> <fileName> 
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; ERP <socLow> <fiIeName> 

; Peek <fileName> 

; All numbers are in octal 

Peek: Peek.reports ; PeekSum.run assumes this 

; only diagnostic boot files should be kept on this disk — 

; the other kinds change too frequently. 

Boot: 5 CrtTest.Boot 

Boot: 6 MadTest.Boot 

Boot: 1!. PupTest.boot 

Boot: 12 DiskTest.boot 

Boot: 35 KeyTest.boot 

ERP: 30 Swat.ERP ; swat errors 

[BRAVO] 
...bravo stuff... 

Peek writes the contents of User.cm into the Command window as it reads through the file. 
If the file has bad syntax, Peek will call Swat with a description of its complaint (e.g. 
"[ReadNumber] - number contains illegal characters" if it is expecting a number and reads 
something other than 0-7). Typing <ctl>-U will restore the user display. The last item in 
the Command window is what Peek is having trouble with. 



5. PeekSum 

PeekSum reads the file Peek.Reports (the output of Peek) and constructs a summary of the 
errors reported by DMT (see above) for each Alto. PeekSum writes on the file 
'PeekSummary.Tx' a tabulation of the error reports, together with the owner's name and the 
machine's location, retrieved (if possible) from the file Pup-Network. Directory, which is 
maintained by Peek, as described above. 

As Peek is started and stopped, it writes short messages to this effect on Peek.Reports; these 
messages are reproduced at the beginning of PeekSummary.Tx. The number or the local 
network is also written. If Peek.Reports contains multiple reports from a single Alto (which 
is usually the case), PeekSum will record the largest number of errors of each type, over all 
such reports. 

PeekSum will complain and then gracefully stop execution if the files Peek.Reports or 
PeekSummary.Tx are unopenable for some reason. If Pup- Network. Directory is unopenable 
or absent, the otput file PeekSummary.Tx will not include names and locations of Altos, but 
will contain error reports grouped by Alto serial number. 

To run PeekSum, just type: 

> PeekSum 

and the program will go about its business. When it has finished, PeekSummary.Tx should 
be printed. 
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DPrint - Diablo Printer Program 



This program types text files on a Diablo printer connected to the Alto. It is a vanilla 
program with very few features. Use Bravo if DPrint's facilities are inadequate. 

The syntax of the command line is: 

DPrint/switch parameter/switch ... filename filename ... 

The only switch permitted on the word "DPrint" is "/?", which instructs DPrint to pause 
before the beginning of each page. 

One or more parameters may optionally be specified: 

n/W Sets the line width to be n characters. Lines longer than this will wrap around 
to the next line. The default is 75 characters. 

n/L Sets the page length to be n lines. This determines the point at which printout 
will pause (if /P was invoked) and also controls the amount of paper spewed 
when a form-feed is encountered in the file. The default is 66 lines (11 inches) 
if /P is not in effect or 57 lines (9.5 inches) if it is. 

n/M Sets the left margin to be n units of 1/10 inch from the hardware left margin 
of the printer. The default is zero. 

Command line parameters without switches are assumed to be names of text files to be 
printed. If a rile cannot be found or a parameter is otherwise incorrect, you will be 
prompted for the correct value. 

When DPrint pauses, you may either type space to resume printout or "Q" to abort it and 
quit out of the program. DPrint will pause immediately if you strike any key while it is 
printing, and also if the printer becomes not ready. 
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Em Press 



EilmPress has several functions. Its primary use is to convert ordinary text files into Press 
format, and to send the converted files to a Press printing server. Options include the ability 
to produce a Press file without transmitting it, and to transmit Press files that have been 
previously produced. Additional features provide for merging several Press page images into 
a single Press file, and for personalizing individual copies of documents. 

EmPress can distinguish Press files from text files, so it need not be told whether to 
convert. As a text file converter, EmPress is intended for formatting program listings and 
supports only simple formatting operations such as Tab and Form Feed. Bravo trailers are 
ignored. 

Joe Maleson wrote the original program. David Boggs made the modifications that allowed 
transmission of files to printers. Rick Tiberi produced the current version, adding the Press 
file merger and copy personalization facilities, and curing many problems. 

Standard Case: 

To send one or more Press or text files to your default Press printer, using a default font to 
convert the text files, type: 

empress filel file2 file3 ... 

and read no further. The more general command line to EmPress is: 

EmPress[/<global switches>] [<parameters>/<switches>] inputFiles 

The square brackets denote portions of the command line that are optional and may be 
omitted. EmPress will print up to 100 input files. 

Each global switch has a default value which is used if the switch is not explicitly set. To 
set a switch to 'false' proceed it with a 'minus' sign; to set it to 'true' just mention the 
switch. 

Switch Default Function 

/T true [Transmit] will send the resulting press file to a printer. 

/number 8 (text files only) tab width -- see below. 

/H true (text files only) [Headings] will print a heading and page number on 

each page. 



EmPress 
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EmPress recognizes a number of optional parameters which can be set from the command 
line. Parameters set from the command line take precedence over defaults built into the 
program. 

Function 

[Output] the name of tie output file. EmPress uses Swatee 
unless told otherwise, since the output press file is usually sent 
to the printer and then discarded. 

[Copies] the number of copies to print. 

[HostName] the name of the printer. This takes precedence 
over the name following PRESS: in the [HardCopy] section of 
User.cm. 

[Input] the name of an input text file to be formatted and 
saved or transmitted, or of an input Press file to be transmitted. 

a siring without any switches is assumed to be an input file. 

The remaining switches apply to text conversion only. 

[Tab] the width of a tab character in multiples of the width if 
a space character. 

[FontFace] the font to use. You must have 'Fonts. Widths' on 
your disk. 

[PointSize] the point size of the font. 



Parameter 


Default 


string/O 


Swatee 


number/C 


1 


string/H 


none 


string/I 


none 


string 


none 




The ren 


number/T 


8 


string/F 


Gacha 


number/P 


8 
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User.Cm Entries 

The following is a sample User.Cm hardcopy section, configured to use the Menlo Press 
printing server as the preferred printer: 

[HARDCOPY! 

PREFERREDFORMAT: Press 

EARS: Palo 

PRESS: Menlo 

PRINTEDBY: "$" 

FONT: TIMESROMAN 10 MIR 

The FONT entry specifies that TimesRomanlOi (italic) should be used as a default font 
instead of Gacha8 (EmPress's default choice). The second, point size argument, and the 
third, face specification argument are optional. The face argument contains three letters 
specifying weight (M, B, or L), slope (R or I), and expansion (C, R, or E), respectively. 

The PRINTEDBY field, if present, specifies the name to be used in the Name field on the 
break page. The current disk login name will replace the character $. EmPress chooses "$" as 
a default in the absence of a specification. 
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Program operation 

When EmPress encounters a Press file in the input list, it transmits (or stores) any text file 
that it is currently converting, then transmits the Press file. A new break page will be 
printed for each Press file, containing that file's name. EmPress will override the "created 
by" field of a Press file with a name derived as described above. It will fill in blank file 
name and date fields with the obvious defaults. If copies are specified in the command line, 
EmPress will override the number of copies specified in the Press file with the command 
line value. 

EmPress uses the file Swatee for temporary storage while converting text for transmission. If 
in so doing Swatee becomes nearly full, EmPress will suspend formatting, send what has 
accumulated so far, and then press on. This has two desirable consequences: 1) a very full 
disk will not run out of space and 2) some pipelining can take place since the printer can 
munch on the first chunk while EmPress empressifies another. 

Press File Merging 

EmPress will merge several one page Press files into a single one page Press file. This allows 
the outputs of Bravo, Sil, Draw, Markup, etc., to be merged without a separate pass through 
Markup. One additional text or Press file may also be submitted, and it will be printed 
following the one page merge result. 

One invokes the merge feature through one additional global switch, and one additional 
local switch: 

Additional Global Switch: 

/m Merge. All subsequent input files that are not qualified by switches must be 

single-page Press files. They will be merged to form a single (cover) page in the 
Press file result, containing all their Piess specifications. This switch also 
conditions Empress to expect the additional local switches, described just below 
and in the Personalization section. 

Additional Local Switch: 

/d Document. This switch may be used to identify an optional main document, when 

the merge option is used. The file may be a simple text file or a Press file. It will 
follow the one page merge result in each copy printed. 
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Personalization 

This relatively specialized feature is provided to allow the personalization of individual 
copies of a document. Each copy of the document might contain, for instance, the name 
and address of the person for whom it is intended. Up to six lines of personalized 
information can be specified. This information will replace distinctive "key strings" that 
have been placed in the cover page (merged) files or in the main document. 

The key strings must appear in contiguous groups of up to six lines each. The personalized 
information for the current copy, specified in a paragraph of a special Bravo-format 
addressee file or in the command line, will replace the key strings in each group, line for 
line. Thus the personalized information may occur more than once in each document (Dear 
Mr. PARC/SDD: ... yes, you and all the members of the PARC/SDD household can enjoy 
the benefits of ...). Lines in the addressee paragraph for which no keys are provided are 
discarded. 

The default key is "<", forty hyphens ("-"), then ">". If the string "<— title— >" appears 
anywhere in the document, the name of the "main" document (the one specified using the 
Vd" switch) will replace it. 

The "/m" (merge) global switch must be specified before any of these personalization 
specification switches are valid. 

Additional Local Switches: 

/k Key. The item is a key that replaces the default (see above). 

/a Addressee. The item is either the name of a Bravo format file containing a list of 

addressees — one per paragraph, one line in each paragraph for each key line in 
the cover page or main document -- or a literal addressee, enclosed in double 
quotes. In a literal, use hyphens where you wish blanks to appear in the name. 
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Executive User's Guide 



Executive, the Alto command processing subsystem, is the intermediary by which Alto users 
generally invoke other subsystems and ask simple questions about the state of the Alto file 
system. It is just the same as any other subsystem, except that its name is known bv the Alto 
Operating System, and it is invoked by the Operating System whenever the BCPL operator 
"finish" or equivalent is executed. This document describes version 8 of Executive. 



1 . What It Does 

The operation of Executive proceeds thus: 

1. It reads any leftover unexecuted commands from a file called Rem.Cm into a main 
memory command queue. 

2. It begins building up a command line (terminated by a CR). If the command queue 
empties Defore the command line is terminated, additional characters are read from the 
keyboard until a CR is read. Editing is done during this phase. If the command line has 
been empty for about twenty mi nines, the user is assumed to be occupied elsewhere, and the 
diagnostic program Dmt.Boot is invoked either from the disk (if it can be found) or from 
the Ethernet. 

3. The edited command is placed at the front, of the command queue and the command 
queue is analyzed for *-, #-, and ©-substitutions. If something of the form ©filename® is 
discovered in the first line in the command queue, it is replaced by the contents of the 
named file and analysis continues with the first character of the replacement. Executive 
makes no attempt to detect or recover from infinitely recursive replacements. If the 
characters * or # are encountered in a filename in the first line, the file directory is used 
to replicate that filename with appropriate substitutions. This step results in a completely 
edited command line. 

4. The first atom (contiguous sequence of legal file name characters) in the command line is 
analyzed to see whether it is the name of a subsystem in the file directory or the name of a 
command internal to Executive or neither. If neither, then Executive attempts to extend the 
atom into the name of a subsystem or Executive command. Failing in this, it complains and 
resets itself. Otherwise the line is written on the file Com.Cm. Then if the first atom was 
or could be extended into a subsystem name, the rest of the command queue is written on 
Rem.Cm, and the subsystem is invoked with a CallSubSys Operating System call. If it is an 
internal Executive command, the appropriate subroutine is called. The Executive passes the 
switches found on the subsystem name in the user parameters vector of CallSubSys. See the 
documentation of CallSubSys for more details. 

In parallel with these steps, Executive does a few housekeeping chores: 

a. It reads the entire file directory into memory, merges in the names of user-callable 
routines internal to Executive, and sorts the resulting list alphabetically. 

b. Having nothing else to do, it puts a line containing a continuously-updating digital clock 
and the number of free disk pages on the user's screen, and flashes a cursor where the next 
typed character v/ill go. 

A number of characters have special meaning during the editing step (2): 

Null: 
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Linefeed: 

Ignored 

Carriage Return: 

Terminates the line, beginning step 3. 

Control-A: 
Backspace: 

Removes the last character from the line queue. 

Control-W: 

Removes the last item which iooks like a file name from the line queue. 

UpArrow: 
Single quote: 

Causes itself and the next character both to be appended to the line queue, 

regardless of what the next character is. 

Control-U: 

Signals that at the conclusion of step 2 the line queue is to be written on the file 
Line.Cm and its contents replaced by the text "Bravo/n Line.Cm". If one has the 
proper Bravo and User.Cm, this will invoke Bravo on the command line. 

Control-X: 

Performs step 3 on the line queue as it is, returns to step 2. In other v/ords, it 
eXpands @, ", and #. 

Control-C: 
Delete: 



Escape: 



Tab: 



Empties out the line queue, starts over again. 

Interprets the last atom in the line queue as the prefix of a file name; continues 
that file name until it is complete or ambiguous. Flashes the screen if it is 
ambiguous. 

Interprets the last atom of the line queue as the prefix of a file name; types out all 
file names which begin that way. 

Same as "?" except it deletes the atom from the line queue after typing the file 
names. This would be what one would normally use to interrogate the directory. * 
and # work as expected. 

In step 3, several characters have special meaning: 

Semicolon: 
Carriage Return: 

Terminate the line; control goes to step 4. 

Up Arrow: 

If followed by a carriage return, do nothing. If followed by an up arrow, put one 
up arrow in the line queue. If followed by any other character, put both characters 
in the line queue (Ugh!). 

/: 

If followed by another "/", this begins a comment, so scan ahead until finding a 
carriage return or semicolon. If not, put the "/" in the line queue. 
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@: 



Scan ahead until finding another @ (the second @ may be omitted if it comes at 
the end of the command). The atom in betv/een is a file name. Replace the 
@atom@ by the contents of the named file. If the file doesn't exist exactly as 
specified, try extending Ihe specification and forcing a .Cm suffix. 



#: 



Expand the atom using these characters by making a search through the file 
directory. * matches any sequence of file name characters. # matches any single 
character except a period. File names are defined to end with an infinite number 
of periods. The atom is replaced by all file names matching its pattern. Switches 
on the atom, if any, are replicated. 

In step 4, one switch is taken to have special meaning on the subsystem name only. The 
switch /! will set the pause parameter in the call to CallSubSys to true allowing you to enter 
Swat after your program is loaded, but before its fi:*st instruction is executed. This switch, 
if detected, is removed from the command line before Corn.Cm is created. This feature is 
extremely useful if your program is hitting a bug before its first user interaction. 



2. Executive Commands 

The Executive contains a number of subroutines which can be invoked from the command 
line. The commands corresponding to these subroutines can be identified by the extension 
character """, which is illegal in a file name. Executive commands include the following: 

Type.~ FileName ... 

Display the contents of the named file(s) on the screen. After each page, it asks 
whether you want to see more of the current file. A Ctrl-C at this point 
terminates the entire Type command. You can type any files, even binary ones, but 
typing some files will give you more jseful information than typing others. 

Delete.~ FileName ... 

Removes the named files from the directory and frees their disk space. Use this 
command very carefully. Its effect cannot be undone. 

Copy.~ DestFileName <- SourceFileName ... 

Copies a file. If there are several SourceFileNames then the copy will contain the 
concatenation of the information in the source files, in the order listed. 

Rename." OldFileName NewFileName (or NewFileName <- OldFileName) 

Changes the name of OldFileName. NewFileName must not already exist unless 
OldFileName and NewFileName are the same (use this feature to change the 
capitalization of a file name). 

BootFrom. ~ FileName [...Sys.Boot] 

Initiates a software -simulated bootstrap sequence on the file named by FileName. 
Most probably the FileName should have the .Boot extension. Like the OS system 
call BootFrom (which it uses) this command does not actually do a hardware 
bootstrap operation, so it does not re-initialize any Alto hardware or microcode 
tasks. If you don't know what this implies, don't worry about it. 

Quit.- 

Diagnose.- 

Has the effect of BootFrom Dmt.Boot. This commences the running of the 
diagnostic program, which doesn't use the Operating System at all. This is done 
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Login.~ 



automatically after a machine has been idle in Executive for about 20 minutes. If 
Dmt.Boot is not on your disk or you turn the disk off Dmt will be loaded from 
the Ethernet. 

Places your user name and password in the system area of main memory for use 
by programs which interact with access-controlled resources (like timesharing 
systems, for example). 



SetTime.~ 

Sets the Alto's internal time-of^day clock. The time is obtained from the Ethernet 
if possible. Failing that you will be asked to supply the time (and possibly time 
zone) manually in the form 12-jan-78 14:45. Use SetTime/m to bypass the 
Ethernet and set time manually. 

Dump.~ DumpFileName SourceFileName ... 

Writes DumpFile as a structured file (in Dump format) containing the names and 
data of all the SourceFiks. This is a convenient way of packaging up a collection 
of related files into a single composite file that can later be decomposed into its 
constituent parts. See Appendix A for details of Dump format. The primary virtue 
of this particular format is that it is intended to be compatible with the Dump 
format of the Data General Nova DOS operating system, and it is compatible with 
the Tenex subsystem DUMP-LOAD.SAV. 

Load.~ DumpFileName 

This reads through a Dump format file and creates individual files corresponding 
to its constituent parts. The /V switch causes Load to ask you about each 
constituent part, whether to copy it from the DumpFile to an individual file or 
not. Acceptable responses are Y, N, and C. The latter indicates that you would like 
it to be copied, but into a file with a different name than that indicated. You are 
then asked to supply the name you prefer. 



Release. 



Tells you the release number and date of Executive. The release number is also 
shown in the first Executive herald line, just after the slash following "Xerox Alto 
Executive." 



Stand irdRam.~ 

For any Trap except the Swat Trap (#77400) the Alto microcode sends control of 
the emulator task to the microcode Ram for interpretation. StandardRam initializes 
the microcode Ram to send control of the emulator task back to the Rom Trap- 
handling microcode. If you don't initialize the microcode Ram before executing a 
program which 1) uses Traps, and 2) doesn't initialize the Ram itself, then when 
the first Trap happens your machine will probably do something bizarre, but it 
usually will not destroy disk data. 

Install. ~ FileName [...Sys.Boot] 

Causes a customized version of the operating system on the file named by 
FileName to be written on the file Sys.Boot. For further details, please see the 
section on "Installing the operating system" in the Alto Operating System manual. 

BootKeys.~ FileName [...Sys.Boot] 

Did you know that by holding down various combinations of keys on the Alto 
keyboard while pressing the boot button it is possible to get the Alto to bootstrap 
load itself from any file on the disk? (This bootstrap will probably crash fairly 
quickly on any file except one in .Boot format.) Bootstrapping the Operating 
system is simply a special case of this: all keyboard keys up refers to disk address 
0, which by convention is where a copy of the first data page of Sys.Boot is stored. 
To find out what keys to push in order to bootstrap load other files, you use the 
BootKeys command. 
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Resume- FileName [...Swatee] 

The file named by FileName is patched so that its Swatee file pointer is the same 
as the current Swatee file pointer, and then it is loaded in and run. For best 
results, this file should be Swatee, or a copy of a Swatee. If you want to return to 
Swat v/ith an old Swatee (for example, originally you didn't have the right .SYMS 
file) you can say 

Copy.- Swatee <- OldSwatee (no need to do this if Swatee is already 

correct) 
Resume.~ Swat 

Chat.- 
Ftp- 
Scavenger.- 
NetExec- 

These commands load the corresponding programs from the Ethernet. If you have 
the .Run file for one of these, it will be found instead by the normal Executive 
lookup strategy. 

EtherBoot.- octal number 

This command will boot any available Ethernet bootable file provided that you 
know its number. 

PileStat.- FileName ... 

This command will tell you several things about a file: its length in bytes, size in 
pages, seria number and disk address, creation and write dates. If any FileName 
is "of the form octal/s (or octall,octal2/s) the file will be looked up by serial 
number rather than by name. This is useful if Scavenger or some other program 
gives you a serial number without telling you the name. 



3 . User.Cm Entries 

The Executive section of User.Cm may contain several commands to the Executive. Most of 
these are command lines to be executed if some event is noted (see the Operating System 
documentation for a description of events). In addition to the standard events, hxecutive 
will post eventClockWrong if it finds the value of the time-of-day clock unreasonable. 

The number of text lines in the user command window can be set from User.Cm using the 
selector userDisplayLines: followed by a number. You are advised not to set this number 
higher than its default value (currently 16), but you might want to reduce the number in 
order to leave more memory space for your directory if you have a large number of files 
(say, more than 300). 



4. Dump Format 

A dump file is a sequence of blocks of eight-bit bytes. The first byte of each block is the 
block type. A typical dump file might look like: 

<name blockXdata block !>...< data block n> 

<name blockXdata block l>...<data block m> 
<end block> 

Name Block - Type=#377 
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A name block contains two bytes of file attributes and then the file name. The file 
attributes are used by the Nova operating system; Alto Dump.~ sets these bytes to 0, and 
Alto Load.~ ignores them. The file name is a sequence of ASCII characters terminated by a 
byte. 

Data Block - Type=#376 

A data block contains two bytes of byte count (high-order byte first), two bytes of 
checksum (high-order byte first), and a sequence of data bytes. The byte count must be less 
than or equal to 256 for compatibility with Novas, and the count does not include the 
checksum or byte count; only trie data bytes are counted. Novas do not handle data blocks 
with byte counts of or 1 correctly. Alto Dump.~ will not produce such blocks unless 
forced to dump a file whose length is less than 2 bytes. The checksum is a 16-bit add 
ignoring carry, over the data and byte count. If the block has an odd number of bytes, the 
last byte is NOT included in the checksum computation. 

Error Block - Type=#375 

Novas generate error blocks. Alto Dump.~ does not. Alto Load.~ terminates if it encounters 
one. 

End Block - Type=#374 

An end block has no contents and terminates a Load.~. 

Date Block - Type=#373 

Date blocks with six bytes of date are generated by Nova RDOS. Alto Dump.~ does not 
generate them; Alto Load.~ ignores them. 

N.B. This appendix is included thanks to David Boggs. 
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Find - a file searching subsystem 



The Find subsystem allows you to search text files at very high speed on an Alto. Examples 
of such files might be an address/telephone list, a source program, or a library catalog. 

Find basically looks for all the occurrences of a pattern in a file, just like doing repeated 
Jump commands in Bravo. A pattern is just a character sequence, except for the following: 

# in a pattern means "any character at all", e.g. CAP and CUP count as occurrences of 
the pattein C#P. 

~ in a pattern means "allow one character in the occurrence to disagree with the 
corresponding character in the pattern". For example, LAP, CUP, and CAT all count as 
occurrences of the pattern ~CAP (or CAP~ or C~AP). Two ~s mean "allow two 
disagreements", and so on. Note that "disagreement" only means substituting one character 
for another: it does not include insertions (e.g. CLAP for CAP), deletions (CP for CAP), or 
transpositions (CPA for CAP). 

If you really want to have a pattern containing # or ~, you have to type a ' before it, 
e.g. to search for the character sequence ATOM #, you have to type ATOM '#. 

Unless you use the /c switch described below, upper and lower case letters are 
considered identical, e.g. Cap, cap, and CAP all count as occurrences of CAP or of cap. 

Unless you use the /s switch described below, blanks (spaces) in the file are completely 
ignored, e.g. CAP counts as an occurrence of CAP; blanks in the pattern are also ignored. 

There are two ways to invoke Find. The first way just searches a file for one pattern: 

>Find filename pattern 
(Since the Executive does something special about @, #, %, *, t, and ; in command lines, 
you must precede any of these characters in your pattern by a '. This is in addition to any 
s vou may need as described in the preceding paragraph.) The second way only specifies 
the file: 

>Find filename 
and Find then prompts you repeatedly for patterns. To leave Find when using it this way, 
use shift-Swat or type an empty pattern (just type <return> when Find says Pattern:). You 
can also use Find to search several files together, by invoking it with 

>Find/m filenamel ... filenamen 
which also prompts you for patterns. 

In any of the above command lines, you can also use the /s switch, i.e. any of the forms 

>Find/s filename pattern 

>Find/s filename 

>Find/ms filenamel ... filenamen 
This causes Find to treat spaces (blanks) just the same as any other character in the file and 
in the pattern. 

In any of the above command lines, you can also use the /c switch, which causes Find to 
treat upper and lower case letters as different from each other. 

After completing the search, Find displays at the top of the screen a summary of the form: 

79 occurrences, 1200 ms, 150 pages 
giving the total number of occurrences, the time in milliseconds, and the number of disk 
pages in the file. In the remainder of the screen, Find displays the line containing each 
occurrence of a pattern, with the occurrence indicated in boldface. To the left of the line, 
Fi:nd displays the character position in the file when: the occurrence was found. After each 
screenful, Find waits for you to type <space> if you want more, or <del> if you don't. 

In addition to displaying matches on the screen, Find always writes the lines containing 
matches on a file called Find. Matches. However, it only writes those matches which it 
displayed, so if you stopped the display of matches with <del>, only those matches you 
actually saw will appear on the file. 
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What Find finds for you is all the "items" containing occurrences of the pattern. Normally 
an "item" is just a single line of text, delimited by <cr> on both ends. However, Find also 
knows about two other kinds of items: Bravo paragraphs, and groups of lines separated from 
each other by a blank line. If you use the /p (tor Paragraph) switch, Find will show 
(display and v/rite on Find. Matches) the entire Bravo paragraph containing the occurrence. 
If you use the /b (for Blank line) switch, Find will show everything surrounding the 
occurrence up to the next preceding and following blank line. 

Find produces a large number of error messages. The messages 

Pattern too long 

Can't p real locate 

RAM full 
all mean the same thing, namely that your pattern is too long or too complicated 
(unfortunately, it is too complicated to explain exactly what "too complicated" means). The 
message 

Can't load RAM 
means that your Alto has old or non-standard ROMs and Find can't do what it needs to do: 
you should contact a hardware maintained (This should never happen on Alto II's.) 

Find has many obvious limitations. They can all be removed if people complain about 
them. The following features could also be added upon request: 

Requiring that a match be delimited by non-alpiianumerics. 

Boolean combinations of matches, maybe. 

Ability to work with Trident disks. 

Possibly other features requested by users. 
Programmers should note that the file searching capability is also available as a library 
package (called FindPkg), so programs can use it as well as people. 

History of changes: 

Release of 1/16/78 

Added /c (distinguish upper and lower case), /p (item = paragraph), and /b (item = 
between blank lines) switches. 
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Alto Pup File Transfer Program 



FTP is a Pup-based File Transfer Program for moving files to and from an Alto file 
system. The program conies in 3 parts: 

1) An FTP Server which listens for file transfer requests from other hosts, 

2) An FTP User, which initiates file transfers under control of either the keyboard 
or the command line, and 

3) A User Telnet for logging into a remote host using the Pup Telnet protocol. 



1. Concepts and Terminology 

Tranferring a file from one machine (or "host") to another over a network requires the 
active cooperation of programs on both machines. In a typical scenario for file transfer, a 
human user (or a program acting on his behalf) invokes a program called an "FTP User" 
and directs it to establish contact with an "FTP Server" program on another machine. Once 
contact has been established, the FTP User initiates requests and supplies parameters for the 
actual transfer of filet;, which the User and Server proceed to carry out cooperatively. The 
FTP User and FTP Server roles differ in that the FTP User interacts with the human user 
(usually through some sort of keyboard interpreter) and takes the initiative in user/server 
hteractions, whereas the l^TP Server plays a comparatively passive role. 

The question of which machine is the FTP User and which is the FTP Server is completely 
independent of the direction of file transfer. The two basic file transfer operations are 
caled "Retrieve" and "Store"; the Retrieve operation causes a file to move from Server to 
User, whereas Store causes a file to move from User to Server. 

The Alto FTP subsystem contains both an FTP User and an FTP Server, running as 
independent processes. Therefore, to transfer files between a pair of Altos, one should start 
up the FTP subsystem on both machines, then issue commands to the FTP User process on 
one machine directing it to establish contact with the FTP Server process in the other 
machine. Subsequent file transfers are controlled entirely from the FFP User end, with no 
human intervention required at the Server machine. 

Transferring files to or from a Maxc system or an 1FS involves establishing contact with 
FTP Server processes that run all the time on those machines. Hence, one may simply 
invoke the Alto FTP subsystem and direct its FTP User process to connect to the machine. 

In the descriptions that follow, the terms "local" and "remote" are relative to the machine 
on which the FTP User program is active. That is, we speak of typing commands to our 
"local" FTP User program and directing it to establish contact with an FTP Server on some 
"remote" machine. A Retrieve command then copies a file from the "remote" file system to 
the "local" file system, whereas a Store command copies a file from the "local" file system 
to the "remote" file system. Furthermore, we refer to "local" and "remote" filenames. These 
must conform to the conventions used by the "local" and "remote" host computers, which 
may be dissimilar (for example, Alto versus Maxc). The Alto FTP knows nothing about 
Maxc filename conventions or vice versa. 

The Alto FTP subsystem also includes a third process, called a "User Telnet", which 
simulates a terminal in a manner exactly analogous to the Chat subsystem (though lacking 
some of its finer features). By this means, you may log in to a file sytem machine to 
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perform operations not directly available via the basic file transfer mechanisms. If you log 
into Maxc, it is even possible to run "PupFTP", tiie Maxc FFP User program, and direct it 
to establish contact with the FTP Server in your own Alto. You should probably not. try 
this unless you really understand what you are doing, however, since the terms "local" and 
"remote" are relative to Maxc rather than to your Alto (since the FTP User program is 
running on Maxc in this case), which can be confusing. 



2. Calling the FTP Subsystem 

A number of options are available when running FTP. The program decides which parts of 
itself to enable and where user commands will come from by inspecting the command line. 
The general form of the command line to invoke FTP looks like: 

FTP[/<Global-switches>] [<Host-name> [<Command-list>] ] 

The square brackets denote portions of the command line that are optional and may be 
omitted. 

Global switches, explained below, select some global program options such as using the 
Trident disk instead of the Diablo. The first token after the <globaJ-switches>, if present, 
is assumed to be a <host-name> (a discussion of which appears later in the description of 
the "Open" command). The User FTP will attempt to connect to the FTP Server on that 
host. After connecting to the server, if a <command-list> is present, an interpreter is 
started which feeds these commands to the User FTP. When the command list is exhausted, 
FTP returns to the Al.o Executive. If no command list is present, an interactive keyboard 
command interpreter is started. 

Each global switch has a default value which is used if the switch is not explicitly set. To 
set a switch to 'false' proceed it with a 'minus' sign (thus FTP/-S means 'no Server'), to set 
a switch to 'true' just mention the switch. 

Switch Default Function 

/S true [Server] starts the FrP Server. The Server is not started if the User 

is enabfed and is being controlled from the command line. 

/U true [User] starts the FTP User. As explained above, the interactive 

command interpreter or the command line interpreter will be started 
depending on the contents of the command line. 

/C true [Chat] starts the Telnet. The Telnet is not started if the User is 

enabled and is being controlled from the command line, or if the 
system disk is TPO. 

/T false [Trident] sets the system disk to be a Trident drive. The default is 0, 

but can oe changed by following the /T with a unit number between 
and 7 (thus FTP/T5 means use Trident unit 5). User and Server 
commands apply to files on this disk but command line input is still 
taken from Com.cm on the Diablo drive. 



/L 



[Log] causes all output to the User FTP window to also go to the file 
'FTP. log" on DPO, overwriting the previous contents. Log is true if 
the User is enabled and is being controlled from the command line. 



/A false [Append Log J enables the log but appends to FTP.log rather than 

overwriting it. 
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/E true 



[Error] causes FTP to ask you if you want t.") continue when a non- 
fatal error happens during execution of a command line. FTP/-E 
will cause FTP to automatically recover from non fatal errors without 
consulting you. 



/R true [Ram] allows FTP to use some microcode which speeds things up 

slightly. If your Alto has no ram, this switch is ignored. 

/B false [Boot] creates 'FTP.Boot' for distribution to boot servers. 

/D false [Debug] starts FTP in debug mode. 

The rest of the global switches are explained below under 'Server Options'. 

3 . The FTP Display 

The top inch or so of the display contains a title line and an error window. The title line 
displays the release date of that version of FIT, the current date and time, the machine's 
internetwork address, and the number of free pages on the disk. The error window displays 
certain error messages if they arrive from the network (errors are discussed in more detail 
bekw). A window is created below the title line for each part of FTP which is enabled 
during a session (server, user, and telnet). 

If the FTP Server is enabled, it opens a window and identifies itself. If a User FTP 
subsequently connects to this Server, the User's network address will be displayed. The 
Server will log the commands it carries out on behalf of the remote User in this window. 
The Server is not enabled when FIT is being controlled from the command line. 

The FTP User opens the next window down and identifies itself. The command herald is 
an asterisk. 

The User Telnet opens the bottommost window, identifies itself, and waits for a host name 
to be eiteied. The Telnet is not enabled when FTP is being controlled from the command 
iine. 

3.1. Directing Keyboard input to the User and Telnet Windows 

The bottom two unmarked keys control which window gets characters from the keyboard. 
Hitting the unmarked key to the right of 'right-shift' (also known as the 'Swat key') directs 
keyboard input to the Telnet window. Hitting the unnarked key to the right of the 'return' 
key (also known as the 'Chat key')- directs keyboard input to the FTP User window. The 
window which currently owns the keyboard will blink a cursor at the next character position 
if it is waiting i or type-in. 



4. K e yboard Command Syntax 

FTP's interactive command interpreter presents a user interface very similar to that of the 
Aito Executive. Its command structure is also very similar to that of the Maxc Pup FTP 
program (I'upFTP), and the Maxc ArpaNet FTP "program (FTP). The standard editing 
characters, command recognition features, and help facility (via "?") are available. 
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4.1. Keyboard Commands 

OPEM <host name> 

Opens a connection to the FTP Server in the specified host. FTP permits only one 
user connection at a time. In most cases the word "OPEN" may be omitted: i.e., a 
well formed <host name> is a legal command and implies a request to "OPEN" a 
connection. FTP will try for one minute to connect to the specified host. If you 
made a mistake typing the host name and wish to abort the connection attempt, hit 
the middle unmarked key (to the right of <return>). 

Ordinarily, the host name can be a string, e.g., "Maxc". Most Altos and Novas have 
names which are registered in Name Lookup Servers. So long as a name lookup server 
is available, FTP is able to obtain the information necessary to translate a known host 
name to an inter-network, address. 

If the host name of the server machine is not known, you may specify an inter- 
network address in place of the host name. The general form of an inter-network 
address is: 

< network > # <host> # <socket> 

where each of the three fields is an octal number. The <network> number designates 
the network to which the Server host is connected (which may be different from the 
one to which the User host is connected); this (along with the "#" that follows it) 
may be omitted if the Server and User are known to be connected to the same 
network. The <host> number designates the Server host's address on <network>. The 
<socket> number designates the actual Server process on that host; ordinarily it should 
be omitted, since the default is; the regular FTP server socket. Hence, to connect to 
the FTP server running in Alto host number 123 on the directly-connected Ethernet, 
you should say "OPEN 123#" (the trailing "#" is required). 

CLOSE 

Closes the currently open User FTP connection. 

LOGIN <user name> < password > 

Supplies any login parameters required by the remote server before it will permit file 
transfers. FTP will use the user name and password in the Operating System, if they 
are there. Logging into FTP will set the user name and password in the OS (in the 
same manner as the Alto Executive's "Login" command). 

When you issue the "Login" command, FTP will first display the existing user name 
known to the OS. If you now type a space, FrP will prompt you for a password, 
whereas if you want to provide a different user name, you should first type that name 
(which will replace the previous one) followed by a space. The command may be 
terminated by carriage return after entering the user name to omit entering the 
password. 

The parameters are not immediately checked for legality, but rather are sent to the 
server for checking when the next tile transfer command is issued. If a command is 
refused by the server because the name or password is incorrect, FTP will prompt you 
as if you had issued the LOGIN command and then retry the command. Hitting 
delete in this context will abort the command. 

A user name and password must be supplied when transferring files to and from a 
Maxc system or an IFS. The Alto FTP Server requires a user-password to be supplied 
if the server machine's disk is password- protected and if the password in the server 
machine's OS does not match the password on the disk. Thus if the OS was booted 
and FTP invoked because a Request-for-Connection was received (which bypasses 
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password checking), FTP will refuse access to files unless a password is supplied. 
However if the OS was booted normally, FTP assumes that the disk owner (who knew 
the password) will control access by using the server option switches. The user-name 
is ignored. 

CONNECT <di rectory name> < password > 

Requests the b FP server to "connect" you (in the Tenex sense) to the specified 
directory on the remote system. The password may be omitted by typing carriage 
return after the directory name. As with LOGIN, these parameters are not verified 
until the next transfer command is issued. At present, the "Connect" command is 
meaningful only when transferring, files to or from a Maxc system or an IFS; the Alto 
FTP server currently ignores connect requests. If the "multiple directory" feature of 
the Alto Operating System ever comes into widespread use, this may be changed. 

RETRIEVE < remote filename > 

Initiates transfer of the specified remote file to the local host. The syntax of <remote 
filename> must conform to the remote host's file system name conventions. 

If the server can find the file, FTP will then print out the complete filename followed 
by the message "to local file < local filename> [01d|New Tile]", where the local 
filename is generally the same as the remote filename without directory or version. 
At this point you may make one of three choices: 

1. Type Carriage Return to cause the data to be transferred to < local filenameX 

2. Type Delete to indicate that the file is not to be transferred. 

3. Type any desired local filename followed by Return. The previous local filename 
will disappear, the new filename will replace it, and FTP will tell you whether a 
file exists with that name. This filename must conform to local conventions. 
You now have the same three choices. 

If the remote filename designates multiple files (the remote host permits "*" or some 
equivalent in file names), each file will be transferred separately and FTP will ask you 
to make one of the above three choies for each file. At present, only Maxc and IFS 
support this capability. That is, you may supply "*"s in the remote filename when 
retrieving files from "Tenex or an IFS, but not when retrieving fies from another 
Alto. 

STORE <local filename> 

Initiates transfer of the specified local file to the remote host. Alto file name 
conventions apply to the < local filename>; "*" expansion is not supported. FTP will 
suggest a remote filename to which you should respond in a manner similar to that 
described under RETRIEVE except that if you supply a different filename, it must 
conform to the remote file system's conventions. The default remote filename is one 
with the same 'name body' (name and extension) as the local file; the remote server 
defaults other fields as necessary. If the remote host is a Maxc system or an IFS, then 
the directory is that most recently supplied in LOGIN or CONNECT commands and 
the version is the next higher. 

DUMP < remote filename> 

Bundles together a groip of files from the local file system into a 'dump-format' file 
(see the Alto Executive documentation for the dump-file format and more on dump- 
files in general) and stores the result as < remote filenameX FTP will ask you for the 
names of local files to include in the dump-file. Terminate the dump by typing just 
< return > when FTP asks for another filename. By convention, files in dump-format 
have extension '.dm'. 

LOAD (remote filename> 
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Performs the inverse operation of DUMP, unbundling a dump-format file from the 
remote file system and storing the constituent files in the local file system. For each 
file in the dump-file, FTP will suggest a local file name and tell you whether a file 
by that name exists on your disk. You should respond in the manner described under 
RETRIEVE. 

LIST <remote file designator> 

Lists all files in the remote file system which correspond to <remote file designator). 
The remote file designator must conform to file naming conventions on the remote 
host, and may designate multiple files if "*" expansion or some equivalent is supported 
there. If the <remote filename) is terminated by a comma, FTP prints a prompt of 
"**" at the left margin and prepares to accept one or more subcommands. These 
subcommands request printout of additional information about each file. To 
terminate subcommand input, type a <return> in response to the subcommand prompt. 
The subcommands are: 

Type Print file type and byte size. 

Length Print length of file in bytes. 

Creation Print date of creation. 

Write Print date of last write. 

Read Print date of last read. 

Times Print times as well as dates. 

Author Print author (creator) of file. 

Verbose Same as Type+Write+Read+Author. 

Everything Print all information about the file. 

This information is only as reliable as the Server that provided it, and not all Servers 
provide all of these file properties. Altos derive much of this information from hints, 
so do not be alarmed if it is sometimes wrong. 

DELETE < remote filename) 

Deletes Xremote filename) from the remote filesystem. The syntax of the remote 
filename must conform to the remote host's file system name conventions. After 
determining that the remote file exists, FTP asks you to confirm your intention to 
delete it. If the remote filename designates multiple files (the remote host permits "*" 
or some equivalent in file names), FTP asks you to confirm the deletion of each file. 

RENAME <old filename) <new filename) 

Renames <old filename) in the remote filesystem to be <new filename). The syntax 
of the two filenames must conform to the remote host's file system name conventions, 
and each filename must specify exactly one file. 

QUIT 

Returns control to the Alto Executive, closiing all open connections. 

TYPE <data type) 

Forces the data to be interpreted according to the specified <data type), which may be 
TEXT or BINARY. Initially the type is UNSPECIFIED, meaning that the source 
process should, if possible, decide on the appropriate type based on local information. 

BYTE-SIZE <decimal number) 

Applicable only to files of type Binary, BYTE-SIZE specifies the logical byte size of 
the data to be transferred. The default is 8. 

EOL <convention> 

Applicable only to files of type Text, EOL specifies the End-of-Line Convention to 
be used for transferring text tiles. The values for <convention> are CR, CRLF, and 
TRANSPARENT. The default is CR. 

DEVICE <device> 
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Causes <device> to be used as the default device in data transfer commands 
(essentially it causes <device> to be attached to all remote filenames that do not 
explicitly mention one). The punctuation separating <device> from the other 
components of a remote filename should not be included. For example you might 
specify "Device DSK" to Tenex, not "Device DSK:" 

DIRECTORY directory name> 

Causes <directory name> to be used as the default remote directory in data transfer 
commands (essentially it causes <directory-name> to be attached to all remote 
filenames that do not explicitly mention a directory). Specifying a default directory 
in no way modifies your access privileges, whereas CONNECTing gives you 'owner 
access' (and usually requires a password). Explicitly mentioning a directory in a file 
name overrides the default directory, which overrides the connected directory, which 
overrides the login directory. Punctuation separating <directory name) from other 
parts of a remote filename should not be included. For example you might type 
'Directory Alto" not "Directory <Alto>". 

USER 

Allows you to toggle switches which control operation of the FTP User. There is 
current!}' only one: DEBUG, which controls display of protocol interactions. Warning: 
this printout (and the corresponding one in the SERVER command below) sometimes 
includes passwords. 

SERVER 

Allows you to toggle switches which control operation of the FTP Server. The 
switches are PROTECTED, OVERWRITE, KILL, and DEBUG. The first three are 
explained below under 'Server Options'. 

TELNET 

Allows you to toggle switches which control operation of the Telnet. There is 
currently only one: CLOSE, which closes the Telnet connection if one is open, and 
clears the Tslnet window. 



5. Command Line Syntax 

The User FTP can also be controlled from the command line. As explained above, the first 
token after the subsystem name and server switches must be a legal host name; if the User 
FTP can't connect to the FTP Server on that host it will abort and return control to the 
Alto Executive. If a command list follows the host name, the command line interpreter is 
invoked instead of the interactive keyboard interpreter. This permits the full capabilities of 
the Alto Executive (filename recognition, "*'■" expansion, command files, etc.) to be used in 
constructing commands for FTP. 

Each command is of the form: 

< Keyword >/<SwitchList> <arg> ... <arg> 

To get a special character (any one of "*#';") past the Alto Executive, it must be preceded 
by a single quote. To get a V" into an FTP argument, the "/" must be proceeded by two 
single quotes (the second one tells FIT* to treat the "/" as an ordinary character in the 
argument, and the first one gets the second one past the Alto Executive). 

Unambiguous abbreviations of command keywords (which in most cases amount to the first 
btter) are legal. However, when constructing command files, you should always spell 
commands in full, since the uniqueness of abbreviations in the present version of FTP is 
not guaranteed in future versions. 
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A command is distinguished from arguments to the previous command by having a switch 
on it, so every command must have at least one switch. The switch "/C" has no special 
meaning and should be used on commands where no other switches are needed or desired. 

5.1. Command Line Errors 



Command line errors fall into three groups: syntax errors, file errors, and connection errors. 
FTP can recover from some cf these, though it leaves the decision about whether to try up 
to you. 

Syntax errors such as unrecognized commands or the wrong number of arguments to a 
command cause FTP's command interpreter to get out of sync with the command file. 
FTP can recover from syntax errors by simply ignoring text until it encounters 
another command (i.e. another token with a switch). 

File errors such as trying to retrieve a file which does not exist are relatively harmless. 
FTP recovers from file error:; by skipping the offending file. 

Connection errors such as executing a store command when there is no open 
connection could cause FTP to crash. FTP can't recover from connection errors. 

When FTP detects an error, it displays an error message in the User window. If the error is 
fatal, FTP waits for you to type any character and then aborts, causing the Alto Executive 
to flush the rest of the command line, including any commands to invoke other subsytems 
after FTP. If FTP can recover from the error, it asks you to confirm whether you wish to 
continue. If you confirm, it plunges on, otherwise it aborts. The confirmation request can 
be bypassed by invoking FTP with' the global error switch false (FTP/-E ...) in which case it 
will plunge on after all non fatal errors. If you aren't around when an error happens and 
you nave told FTP to get confirmation before continuing after an error, the remote Server 
will probably time out and close the connection. If you then return and tell FTP to 
continue, it will get a fatal connection error and abort. 

5.2. Command Line Commands 

OPEM/C <host name> 

See description in "Keyboard commands". The first token after the subsystem name 
and global switches is assumed to be a host name and no OPEN verb is required (in 
fact if you supply it, FTP will try to make a connection the host named OPEN which 
is almost certainly not what you want). 

CLOSE/C 

Closes the currently open User FTP connection. 

LOG1N/C <user name) < password > 

See description in "Keyboard commands". The <password> may be omitted. 

LOGIN/Q <user name> 

Causes FTP to prompt the user for the password. This form of LOGIN should be 
used in command files since including passwords in command files is bad practice. 

CONNECT/C <directory name> <password> 

See description in "Keyboard commands". The <password> may be omitted. 

CONNECT/Q<directory name> 

Causes FIT to prompt the user for the password needed to connect to the specified 
<directory name>. r Ihis form of CONNECT should be used in command files since 
including passwords in command files is bad practice. 
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RETRIEVE/C <remote filename> ... <remote filename> 

Retrieves each <remote filename> and writes it in the local file system, constructing a 
local file name from the name body of the actual remote file name as received from 
the Server. FTP will overwrite an existing file unless the /N (No overwrite) switch is 
appended to the RETRIEVE command keyword. If the remote host allows "*" (or 
some equivalent) in a filename, a single remote filename may result in the retrieval of 
several files. (Note that you must quote the "*" to get it past the Alto Executive's 
command scanner.) As mentioned previously, this capability is implemented only by 
Maxc and IFS FTP Servers at present. 

RETRIEVE/S <remote filename> <loc£l filename> 

Retrieves < remote filename> and names it < local filename> in the local file system. 
This version of RETRIEVE must have exactly two arguments. FIT will overwrite an 
existing file unless the /N (No overwrite) switch is also appended to the RETRIEVE 
command keyword. The remote filename should not cause the server to send multiple 
files. 

RETRIEVE/U <remote filename> ... <remote filename> 

Retrieves < remote filename> if its creation date is later than the creation date of the 
local file. A file will not be retrieved unless a local file with name and extension 
equal to the name and extension of the remote filename exists, or if the FTP server 
does not send a CREATION-DATE property. This option can be combined with 
RETRIEVE/S to rename the file as it is transferred. 

RETR1EVE/V 

Requests confirmation from the keyboard before writing a local file. This option is 
useful in combination with the Update option since creation date is not a fool-proof 
criterion for updating a file. 

STORE/C <!ocal filename> ... <lo:aI filename> 

Stores each < local filename> on the remote host, constructing a remote filename from 
the name body of the local filename. A local filename may contain ,, * ,, f since it will 
be expanded by the Alto Executive into the actual list of "filenames before the FTP 
subsystem is invoked. 

STORE/S <local filename> <remote filename> 

Stores < local filename> on the remote host as <remote filenameX The remote 
filename must conform to the file name conventions of the remote host. This version 
of store must have exactly tv/o arguments. 

DUMP/C <remote filename> <Iocal filename>...<local filename> 
See the description in "keyboard Commands". 

LOAD/C < remote filename> 

See the description in "keyboard Commands". If the /V switch is appended to the 
LOAD command keyword, FTP v/ill request confimation before writing each file. 
Type <return> to write the f i e, <del> to skip it. FTP will overwrite an existing file 
unless the /N (No overwrite) switch is appended to the LOAD command keyword. 

DELETE/C < remote filename> 

See the description in "Keyboard Commands". If the /V switch is appended to the 
DELETE command keyword, FTP will request confirmation before deleting each file. 
Type <return> to delete the file, and <del> (oops!) if you don't want to delete it. 

COMPARE/C <remote filenameX.. < remote filename> 

Compares the contents of < remote filename> with the file by the same name in the 
local file system. It tells you how long the files are if they are identical or the byte 
position of the first mismatch if they are not. This command is not available in the 
Keyboard command interpreter simply because there is no space left (when the 
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command line interpreter is running there is no Telnet and no Server so there is lots 
of space). 

COMPARE/S <remote filename> < local filename> 

Compares < re mote filename> with <local filename>. The remote filename must 
conform to the file name conventions of the remote host. This version of COMPARE 
must have exactly two arguments. 

RENAME/C <old filename> <new filename> 

See the description in "Keyboard Commands". 

TYPE/C <data type> 

See the description in "Keyboard Commands". 

BYTE-SIZE/C <decimal number> 

See the description in "Keyboard Commands". 

EOL/C <convention> 

See the description in "Keyboard Commands". 

DEVICE/C 

See the description in "Keyboard Commands". 

DIRECTOR Y/C <default directory> 

See discription in "Keyboard commands". 

DEBUG/C 

See the description of the DEBUG subcommand under the USER command in 
"Keyboard Commands". 



6. Using a Trident Disk 

Starting FTP with the /T global switch causes FIT to store and retreive files from a Trident 
disk. Accessing a file on a Trident requires more code and more free storage than accessing 
a file on the Diablo. Since FTP is very short on space, only an User or a Server FTP is 
started when the /T switch is set. The default is to start a User FTP, but specifying no user 
(FTP/T-U) or specifying a server (FTP/TS) will start a Server FTP instead. 



7. Telnet 

FrP provides a simple User Telnet as a convenience for logging into a remote host (e.g., 
Maxc) to poke around without having to leave the FTP subsystem and start Chat. It lacks 
most of the creature comforts Chat provides, such as automatic attaching to detached jobs, 
automatic logging in, etc. The Telnet is not enabled when the User FTP is being controlled 
from the command line. When the Telnet does not have an open connection, it waits for 
you to type a host name with the syntax explained above for the OPEN command, and then 
attempts to connect to the specified host. If you wish to abort the connection attempt, hit 
the bottom unmarked key (opposite right-shift). You can get a larger Telnet window by not 
starting a server (type 1FTP/-S to the Executive). 
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8. File Properties 

Without explicit information from the file system, it is often difficult to determine whether 
a file is Binary or Text, if Binary, what its byte-size is, and if Text, what End-Of-Line 
convention is used. The User and Server FTPs use some simple heuristics to determine the 
correct manner in which to transfer a file. The heuristics generally do the right thing, in 
the face of incomplete information, and can be overridden by explicit commands from a 
human usur who knows better. 

The FTP protocol specifies a standard representation for a file while in transit over a 
network. If the file is of type Binary, each logical byte is packed right-justified in an 
integral number of 8-bit bytes. The byte-size is sent as a property along with the file. If 
the file is of type Text, each character is sent right-justified in an 8-bit byte. An EOL 
convention may be sent as a file property. The default is that <return> marks the end of a 
line. 

8 .1. File Types 

FTP determines the type of a local file by reading it and looking for bytes with the high- 
orde bit on. If any byte in the file has ajiigh-order bit on, the file is assumed to be Type 
Elinary, otherwise it is assumed to be Type lext. 

FTP will w:irn you, but allow you to send what it thinks to be a text file as type Binary, 
since no information is lost. It will refuse to send a binary file as type text. 

Don't specify a Type unless you know what you are doing. The heuristic will not 
lose information. 

8.2. Byte-Size 

If a file is type Binary, the byte-size is assumed to be 8 unless otherwise specified. The 
FTP User and Server will both accept binary files of any byte-size and v/rite them as 8 bit 
bytes on the disk. No transformation is done on the data as it is written to the disk: it is 
stored in network default format. Since there is no place in the Alto file system to save the 
byte-size property, it is lost. 

Similarly, requests for Binary files will be honored with any byte size, and whatever is on 
the disk will be sent to the net without transformation. Since Alto files have no byte size 
information, the byte-size property will be defaulted to 8 unless otherwise specified (by the 
BYTE command), in which case whatever was otherwise specified will be sent as the byte 
size. 

Don't specify a Byte-size unless you know what you are doing. Alto-Alto 
transfers can't go wrong. Alto-Maxc transfers with weird byte-sizes will not work 
unless the byte-size specified in the Alto to Maxc direction is the same as the 
byte-size in which the file was stored on the Alto. If it isn't, the Alto will not 
give any error indication, but the result wiii be garbage. 

8.3. End-of-Linc Conventions 

FTPs are expected to be able to convert text files between the local file system End-Of-Line 
(EOL) convention and the network convention. Conveniently enough, the Alto file system's 
internal representation of a text file is the same as the network standard (a bare <return> 
marks the end of a line). The Alto FTP does not do any transformations on text files. It 
will reftse to store a text file coming in from the net whose EOL convention is CRLF. 
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As an escape to bypass conversion and checking, EOL convention 'transparent' tells both 
ends NOT to convert to network standard, but rather send a file 'as is'. This is included for 
Lisp source files which use EOL convention CRLF and contain internal character pointers 
that are messed up by removing line feed characters. 

Don't specify an EOL convention unless you know what you are doing. If your 
text file is a Lisp source file, specify EOL convention 'Transparent'. 

8.4. File Dates 

The Alto file system keeps three dates with each file: Creation, Read, and Write. FTP treats 
the read and write dates as properties describing the local copy of a file: when the file was 
last «ead and written in the local file system. FTP treats the creation date as a property of 
the file contents: when the file contents were originally created, not when the local copy was 
created. Thus when FIT makes a file on the local disk, the creation date is set to the 
creation date supplied by the remote FTP, the write date is set to 'now' and the read date is 
;et to 'never read . 



9. FTP User Log 

FTP can keep a log (typescnpt) file for the FTP User window. The file name is 'FTP.log'. 
It is always enabled when FTP is being controlled from the command line; otherwise it is 
controlled by the /L and /A global switches. Some keyboard commands do not treat the 
u:.er window as a simple teletype, so the typescript for these commands will not be exactly 
wha: you saw, sigh. 



10. Abort and Error messages 

Error and Abort packets are displayed in a window above the title line. Abort packets are 
fatal; Error packets are not necessarily so. The most common Abort message is "Timeout. 
Good bye", generated when a server process has not received any commands tor a long time 
(typically 5 minutes). 

The most common Error message is "Port IQ overflow" indicating a momentary shortage of 
input buffers at the remote host. Receiving an Error Pup does not imply that the file in 
transit has been damaged. Loss of or damage to a file will be indicated by an explicit 
message in the User FTP v/indow. The next iteration of the Pup protocols will probably 
rename 'Error Pups' to be 'Information Pups'. 



11. Server Options 

Server options are controlled by switches on the subsystem name and subcommands of the 
SERVER keyboard command. There are currently four options: 

switch Default Function 

none If no server option is specified, retrieve requests (disk to net) are 

allowed. Store requests (net to disk) are allowed unless the store 
would overwrite an already existing file. Delete and Rename are not 
permitted. 
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/P false [Protected] Retrieve requests are allowed. No stores are allowed. 

Delete ana Rename are not permitted. 

/O false [Overwrite] Retrieve requests are allowed. Store requests can 

overwrite files. Delete and rename are permitted. 

/K false [Kill] FTP will return to the Alto Exec when the server connection is 

closed. A simple form of remote job entry can be performed if the 
user FTP stores into Rem.cm (Com.cm on Novas). 



12. CLI Examples 

Here are some examples of Command lines. 

To transfer files FTP.run and FTP.syms from the Alto called "Michelson" to the Alto called 
"Morley", one might start up FTP on Michelson (to act as an FTP Server), then walk over to 
Morley and type: 

FTP Michelson Retrieve/c FTP.run FTP.syms 

Alternatively, one could start an FTP server on Morley (invoking it by "FTP/O" to permit 
files to be overwritten on Morley's disk), then issue the following command to Michelson: 

FTP Morley Store/c FTP.run FTP.syms 

The latter approach is recommended for transferring large groups of files such as "*.run" 
(since expansion of the "*" will be performed by the Alto Executive). 

To retrieve User.cm from the FTP server running on Alto serial number 123 (name 
unknown, but it is on the local Ethernet): 

FTP 123'# Retrieve User.cm 

Note that the "/'" must be preceded by a single quote when included in a command line, 
since otherwise the Alto Executive does funny things with it. (Quotes are not necessary 
when typing to FTP's interactive keyboard interpreter). 

To start FTP, have the FTP User connect to Maxc, and then accept further commands from 
the keyboard: 

FTP Maxc 

To retrieve <System>Pup-Network.txt from Maxc and store it on the Alto as 
PupDirectory.bravc, and store PupRTP.bcpl, Puplb.bcpl, and PupBSPStreams.bcpl on <DRB> 
with their names unchanged: 

FTP Maxc Connect/c drb mypassword Retrieve/s <System>Pup-Network.txt 
PupDirectory. bravo Store/c PupRTP.bcpl Puplb.bcpl PupBSPStreams.bcpl 

To retrieve the latest copy of all .RUN files from the <alto> directory, overwriting copies 
on the Alto disk (The single quote is necessary to prevent the Alto Executive from 
expanding the "*"): 

FIT Maxc Ret/c <alto>'*.run 

To update the Alto disk with new copies of all <alto> files v/hose names are contained in 
file UpdateFiles.cm, requesting confirmation before each retrieval: 
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FTP Maxc Dir/c Alto Ret/u/v @UpdateFiles.cm@ 

To store all files with extension .BCPL from the local Alto disk to your login directory, on 
Maxc (the Alto Executive will expand "*.bcpl" before invoking FTP): 

FTP Maxc St/c *.bcpl 

To retrieve <System>Host-name/desc iptor-file.txt;43 (two single quotes are necessary to get 
the "/" past the Alto Executive and the FTP command scanner, and one quote is necessary 
to get the ";" past the Alto Executive): 

FTP Maxc Ret/c <Systern>Host-name'7descriptor-file.txt , ;43 

To send Prog.f4, Data.f4, and Command.f4 to Fortran-Machine and then cause the FrP 
server on Fortran-Machine to quit (presumably to execute Prog.f4 on Data.f4 according to 
the commands in Command.f4): 

FTP Fortran-Machine Store/c Prog.f4 Data.f4 Store/s Command.f4 Rem.cm 

FTP on Fortan-Machine must be started with the /K server option switch, and Command.f4 
should re-invoke FTP as its last act so that the results can be retrieved. 

To release a new version of FTP, I incant: 

@ReleaseAltoFTP.cm@ 

which the Alto Executive expands into: 

FTP Maxc Connect/q Alto Store/c FTP.run FTP.syms Connect/q AltoSource 
Dump/c FTP.dm @ftp.cm@ 

and then into: 

FTP Maxc Connect/q Alto Store/c FTP.run FTP.syms Connect/q AltoSource 
Dump/c FTP.dm ©FtpSubsys.cm@ @FtpPackage.cm@ FTP.cm 

and finally into: 

FTP.run Maxc Connect/q Alto Store/c FTP.run FTP.syms Connect/q AltoSource 
Dump/c Ftp.dm Ftp.bcpl FtpNv.bcpl Ftplnit.bcpl Ftplnitl.bcpl FtpNvInit.bcpl 
FtpUserlnit.bcpl FtpSubsys.decl FtpKbdlnit.bcpl FtpK.bd.bcpl FtpKbdl.bcpl 
FtpKbd2.bcpl RpClilnit.bcp! FtpCli.bcpl FtpClil.bcpl FtpCli2.bcpl 
FtpCl i Util.bcpl FtpMiscb.bcpl FtpMisca.asm FtpServerlnit.bcDl FtpServer.bcpl 
FtpTelnetlniLbcpl FtpTelnet.bcpl FtpKeys.bcpl FtpCmdScanDsp.bcpl FtpMc.mu 
FtpRamTrap.mu CompileFtpmc.cm FtpS T ubsys.cm CompileFtpSubsys.cm 
CompileAltoFtp.cm LoadAltoFtp.cm MakeHiddenFtp.cm Load Hid den Ftp.cm 
ReleaseAltoFtp.cm CompileNovaFtp.cm LoadDosFtp.cm LoadRDosFtp.cm 
FtpProt.decl HpUserProt.bcpl FtnUssrProtFile.bcpl FtpUserProtMail.bcpl 
FtpServProtFile.bcpl FtpServProtivlail.bcpl FtpPListlnit.bcpl FtpPListProt.bcpl 
FtpPListl.bcpl FtpUtillniLbcpl FtpUtilB.bcpl FtpUti A.asm FtpUtilXfer.bcpl 
FtpUtilDmpLd.bcjpl FtpUtilCcmpU.bcpl FtpUtilCompA.asm BlockEq.mu 
FtpOEPInit.bcpl CompileFtpPackage.cm DumpFtpPackage.cm FtpPackage.cm 
Ftp.cm 

To load Ftp.dm from <AltoSource>, expanding it out into its constituent files: 

FTP Maxc Load/c <AltoSource> Ftp.dm 

To cause Memo.ears to be spooled for printing on Ears by the Maxc printing system: 
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FTP Maxc Store/s Memo.ears LPT: 

This also works for Press files and unformatted text files if you know what you are doing. 
It does not do the right thing for Bravo-format files. 

To use FTP as a stop-gap IFS: 

FTP/TUO 

This starts only a server with overwriting of existing files permitted. When using the 
Lricent, there isn't enough space to start both a User and a Server. 



1 3. Nova FTP 

FTP is also available running under Dos Rev 4 and RDos Rev 3. Since the Nova versions 
are nearly identical to the Alto version (the same source files except for initialization), only 
Lhe differences are listed here. 

1) Ignoie all references to display windows. All printout goes to device #11, 
whatever that is. 

2) Ignore all references to 'unmarked keys' such as for aborting connection 
attempts and directing keyboard input to various windows. 

3) Lack of memory and lack of a windowing display made including a Telnet 
ii lpractical on the Nova. 

4) The syntax of the command line is limited to that acceptable to the Nova 
operating system. Warning: the command line examples given above may not all 
work on a Nova. 

5) The Nova OS does not maintain a username or password, so all interactions 
with a Maxc system or an IFS will require the user to supply them. 

6) File creation dates are not supported, so there is no Update option to 
RETRIEVE, and the LIST command does not show dates. 

13.1. FTP releases 

The Neva FTP subsystem consists of a save-file, FTP.SV, and an overlay-file, FTP.BB. You 
must get BCTH files when a new version of FTP is released. If you rename FTP.SV you 
must rename FTP.BB. to have the same name (for instance if you rename FTP.SV to be 
OLDFTP.SV you must also rename FrP.BB to be OLDFTP.BB). * New releases of FTP will 
':>■.;: distributed as dump files with a consistant pair of save- and overlay-files. 

1 3.2. Device codes 

FTP assumes that Nova Ethernet interfaces have device codes 73 and 74, 63 and 64, or 53 
and 54. It will use all interfaces with these codes that seem (from reading some status 
registers) to be Ethernets. The Dos version of FTP assumes that Nova MCA interfaces are 
device code 6 and 7, or 46 and 47. It will use all interfaces with these codes that seem to 
be MCAs. 
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13.3. RDos notes 

FTP is big, and will not run under some RDos systems. If you have trouble, generate a 
smaller system and boot from it when running FTP. FTP disables parts of RDos with 
patches which may not work for versions other than Rev 3. It will NOT work under an 
KDos that uses the memory map hardware. The RDos version does not include MCA 
drivers. 

14. Revision History 

April 1976 

First release. 

May 1976 

/Q swi.ch added to CONNECT. Connection requests to the User FTP and Telnet can be 
aborted. Login prompt changed. 1 minute Timeout added when v/aiting to finish after a 
command line error. User FIT automatically recovers from more "No" responses from the 
remote server. 

June 1976 

Dos versicn released. DIRECTORY and LIST, commands added. Update (/U) option 
added. File creation dates added. 5 minute no-activity timeout added to FTP Server. FTP 
version, time-of-day, and machine address added in top window. "Ding" now flashes only 
the affected window instead of the whole display. 

August 1976 

RDos version released. Same as June release for Dos and Alto. 

October 1976 

DUMP and LOAD commands added to user FTP. KILL command added. Free disk page 
count added to the title line. Verify (/V) switch added to the RETRIEVE command. 

November 1976 

Bug fixes to the October release. 

May 1977 

This version was only released to friends. KILL command removed and turned into a server 
option. DEEUG command moved into new USER and SERVER commands. Trident disk 
option (/T) added. User LIST command improved and Server LIST response implemented. 
Passworc checking by the FTP server implemented. Telnet window enlarged at the expense 
of pcssibly losing information frcm the top of the window if the lines are very full. 
DELETE, RENAME, and DEVICE commands implemented. Much internal reorganization 
so that the protocol modules could be used in IFS and released as a package. 

July 1977 

Global switches changed. <Shift-Swat> should work more reliably now. User LIST 
command further improved. Keyboard command interpreter is much more robust and 
consistant. Command line STORE and DUMP go much faster since they look up files using 
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MDI. FTP/Tx opens Tridem: unit 'x\ LOGIN command added to command line 
interpreter. 

November 1977 

Special microcode added to speed up execution. 

March 1978 

User log option added (see /L and /A switches and 'FTP User Log' section). 
AllocatorDebug switch removed. Mew command line commands COMPARE, OPEN, and 
CLOSE added. Command line errors are handled differently (see /E global switch and 
'Command Line Errors' section). When using a Trident, either a User or a Server FTP is 
started but not both (see the section on Trident disks). 
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EARS, GEARS, SEARS, and Other Related Items 

(Revised 8 April 1975) 
(Revised 21 June 1977) 



The EARS printing system is available in CSL room 2077. The EARS system may 
be accessed directly from any machine on the Ethernet. ALTOs currently may access EARS 
via the program GEARS which is described in this memo. Access to EARS via MAXC is 
described in another memo. The use of PUB with respect to EARS is also described in 
another memo. 



1. EARS 



EARS is a one page per second printing system consisting of an Ethernet, Alto, 
RCG (Research Character Generator), and SLOT/7000. The EARS system is designed to 
spool more than 1000 pages of output on its disk and to print graphic art quality 
documents. Up to 190 individual documents may be spooled simultaneously. 

EARS does no page composition. Page composition is done by other computers on 
the Ethernet. This approach distributes the composition load, minimizes changes to the 
EiARS system software, and allows users to write their own special composition software. 
Th;: standard EARS File Format allows a user to gee at all of the features of EARS while 
also allowing simple pages to be easily composed. 

The EARS system v/ill print multi-page documents in portrait, landscape, or mixed 
mode. The system is designed with the following limits: 

characters/page (including directives) 

text strings/page 

characters/font 

fonts./page 

font sets/document 

pages/document 

words of compressed font storage/font set 

words of guaranteed document storage space 

on disk at connect time 



1. 


15k 


2. 


512 


3. 


128 


4. 


16 


5. 


64 


6. 


500 


7. 


32k 


8. 


600k 
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2. SEARS 

SEARS is the subsystem that may be run on the ALTO named Palo to start the 
EARS system. Once EARS has been started, it displays various information about itself. 
There are two display areas on the ALTO screen. The first is a journal that records ethernet 
transactions and operator requests. The second records current system status such as 
"spooling", "printing", "call key operator", etc. 

The printing system accepts the following keyboard commands from an operator: 

P print 

B backspace printer (5 pages)* 

D delete current file* 

R restart current file* 

C complete current file and halt 

H halt printer 

S spool input 

N no spooling 

Q quit 

W enable auto mode 

Z disable auto mode 

*These commands only work when the printer is in the HALT state. 

When SEARS is executed the system is initialized with both printing and spooling 
enabled. The quit command is the only reliable method to terminate EARS. (Booting the 
machine will merely cause a restart.) 

If the status display area reouests a key operator, the duplicator portion of EARS is 
probably jammed or out of paper. Follow the instructions posted near EARS to remedy this 
problem. 
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3 . GEARS 

GEARS is an interim program that will compose text files and transmit them to 
EARS via the Ethernet. The EARS Alto is named Palo, and is host 3 on 35-Ethernet. 

GEARS may be controlled with global switches, lccal switches, imbedded directives, 

and items in User.cm. In the simplest case, you would t>pe GEARS, followed by any 

number of text file names. Each file will be printed in the default fixed pitch font and 
will receive appropriate headings. 

If the default conditions are not acceptable, all of the capabilities of the system may 
be accessed via the switches and directives. I believe the global switches are self- 
explanatory—if not, try one. (See Summary of Commands.) 

GEARS searches User.cm for a [HARDCOPY] section to set some parameters. 
Currently the network address of an EARS format printer and the 'Printed by' string on the 
break page a n be set from User.cm. Here is an example: 

[HARDCOPY] 
EARS: Palo 
PRINTEDBY: "SDD - $" 

X in the PRINTEDBY string is special: it means insert the Username (from the OS) 
in place of the $ character. The default string for PRINTEDBY is "$". 

EARS font selection is quite flexible. Ears has two font concepts: A font and a 
font set. A font is an arbitrary collection of up to 128 distinct characters while a font set 
is a group of up to 16 fonts. 

Normally a user will select a font from the default set. This font set is maintained 
by EARS and coes not reside on each user's disk. Rather a directory for this font set is on 
each user's disk and is named DEFAULT.ED. A program named FEARS will list the fonts 
in DEFAULT ED by name and by number. A new default font may be selected by name in 
the command line or by number with a global directive. Local font changes are by number, 
ilote the font names must have an extension since FONT.EP is a portrait font and 
FONT.EL is a similar landscape font. 

In general, EARS can completely change font sets between each page. GEARS, 
however, only supports font set changes between text files. A user may generate his own 
font sets by concatinating any sixteen fonts of his choi.e. This is accomplished with the 
local switch G (generate) in the command line. 

First a file FOO.EC should be generated with an editor. The file is a list of up to 
sixteen fonts to be corcatinat.:d. The font names appear on separate text lines and are 
assigned numbers in order of occurence. Fonts specified in the FOO.EC file must either be 
in .EP (EARS portrait) or .EL (EARS landscape) format. Fonts in these formats are found 
on the MAXC <FON1S> directory. Alternatively, .EP and .EL files may be generated from 
.CU (Carnegie format) fonts using the program COMPRESS from the <EARS> directory on 
MAXC. COMPRESS is called with the font(s) to be compressed in the command line 
(COMPRESS FONT1.CU FONT2.CU, etc). Besides creating .EP and .EL files, COMPRESS 
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creates an .ES (EARS specification) file which may be printed and contains information 
about each character. 

After FOO.EC has been created and all of the fonts are on your disk you run 
GEARS FOO/G TEXT. This will print your file TEXT in your font set and generate two 
other files: FOO.ED (EARS directory) and FOO.EM (EARS multiple). After the initial 
generation of a font set run GEARS FOO/S TEXT. 

Global directives must appear at the beginning of a text file and only one global 
directive may appear on a text line. Note that many global directives require a special 
password since they are used for debug only and can produce bizarre results. GEARS makes 
very few consistency checks (e.g., if the line height is set less than the font height, the lines 
merely overlap a little) -- so be careful! 

Local directives may be arbitrarily sprinkled throughout the text with interesting 
results. The coordinate system for page composition is shown in Figure 1. The basic unit 
is .002 inches with the origin in the lower left of a portrait page. Some care should be used 
in applying directives. For example, it is avisable, although not necessary, to change to a 
landscape font if the ?L landscape directive is used. 

A list of the primitive microcode directives that are accessed by the local directives 
is given in Appendix 1. 
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78 



3.1. Summary of Gears Options 



3.1.1. G obal Switches 

/A absolute, no formatting except page breaks 

/D process directive preceded by t (Not control) 

/F generate iniermediate file FOO.EB where FOO is name of 

first text file 

/L print in landscape mode 

/N no heading 

/P proportional default font 

/R long lines truncated instead of wrapped around 

/S small default font 

/T test mode--no EFTP 

/Z reads RCG- format files 

/n make n copies for n = 1 to 9 



3.1 .2. L ocal Swit ches 
FOU7F 

FOO/G 



FOO/S 



Text/H 



FOO/n 



use font FOO (must include extensions listed 
by FEARS) 
generate font set 
for all following files 

use font set FOO 
for all following files 

add this text to the default heading 
on each page - no blanks or slashes 
allowed 

print text file FOO with the TTY Tab set for 
n spaces rathe: 1 than the default value of 8 



Note: Font set and Default font must come before text file name. Font set and/or 
font, specification is optional. As many files as you like may be printed subject to disk 
restrictions (<500 pages). 

GEARS processes four control characters, fourteen global directives, and sixteen 
ocal diiectives. 



3.1.3. Control Characters 

carnage return- end of line 

form feed - end of page 

tab - space to next column 

line feed - ignored 
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3.1.4. Global Directives - fMust be at beginning of file but may be 
embedd ed in a text s tring such as a BCPL comment.T 
tBn. Bottom Margin 
tCn. Clock Frequency in bits/inch* 
tDn. Default font (0-15) 
tGn. Software Left Margin (Gap) 
tHn. Height from one line to next 
tin. Hardware Left Margin* (Indent) 
tLn. Length of line in characters before wrap around. 
tMn. Motor speed in lines/inch* 
tNn. Number of scan lines allowed on page* 
tPn. Password* 

tRn. Raise bottom margin (Hardware)* 
tSn. Change TTY tab stops to n spaces 
tTn. Top Margin. 
tXn. Xerox n copies 

*These parameters are preset and modified for 
debug only. The system ignores these directives 
without the proper password. 



3.1.5. Local Directive fimbedded in text strings! 

tan. Alter text line location to n 

bits from bottom page 
tbn. Blank of .vi«jth n bits 
td. revert to default font with default spacing 
te End of page (same as Form feed) 

tfn Font change to n (0-15) 
thn. Change height from one line to next, 
tin. 1 A relative to text base line (Jump) 
tl Landscape string follows 

to Overlay next character 

trw.h. Solid rectangle of width w and height h. 

Used to generate vertical and horizon :al lines in forms. 

This directive only works after an tfn. that 

selects font RECTANGLE.EP 
tsn. Space modification for next character 
ttn. Tab to line n 

tun. Unusual line— prim; only on «.opy n 
tvn. Vector mode— modify space and width 

""of next character 
twn. Width modification of next character 
t*n. ^escape as in BCPL-ng becomes Ascii 



Note: Unknown directives are ignored so that tt will print t. 
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4. EARS FILE FO RMAT 

This section is included for those who would like to write their own text composers. 
This fik; tyre has an .EB extension on ALTOs and an .EARS extension on MAXC and may 
be sent to Palo via EFTP on an ALTO or COPY on MAXC. The standard EARS file 
format is page oriented. Each section of the print file is blocked in 256 word records. The 
complete lile' is structured as follows: 

Mnemonics Optional? Description 

DL 1 No Display list page 1 

TL 1 No Text line array page 1 



Display list page n 
Text line array page n 
Page directory 
Font directory 
Font memory set 1 
Font specification set 1 



DL n 


Yes 


TL n 


Yes 


PD 


No 


FD 


Yes 


FM 1 


Yes 


FS 1 


Yes 



FM m 


Yes 


FS n 


Yes 


DD 


No 



Font memory set m 
Font specification set m 
Document Directory 

The page layout Tor EARS is shown in Figure 1. The default scan resolution is 500 
scan line/ inch and 500 bits/inch. These numbers are independently variable for special 
applications. 



4.1. Display List fDLl 

EAR 1 ) requires a separate display list for each page. A display list contains strings 
of ascii characters with imbedded directives. Each entry in the display list is an eight bit 
code. Characters have values between and 177 octal. Directives have a value between 200 
and 377. Directives may be either one or tv/o bytes lonj*. Appendix 1 gives the EARS 8- 
bits character and directive code. The DL may also contain up to 40 tab stops. If used, the 
first word of the DL must be -1 followed by 40 tab positions. 
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4.2. Text Line Array fT Ll 

EARS requires initialization information for each text string on a page. A page may have 
512 strings. The TL arra;/ las four entries per text string. 

Entry 

"i distribution index** 

1 byte pointer to first character of string in DL 

2 initial font *128 

3 initial text line location *8 (i.e. YBA *8) 

* w If this entry is zt ro, the corresponding text string is 
printed on all copies. If the entry is n, the string is only 
printed on copy n. The last distribution index for a page 
must have its sign bit set. 

4.3. Pa^e Directory fPDl 

Ears allows up to 256 pages/document. Each page requires four entries in the PD. 

Entry 

C starting record of DL for this page 

(referenced from start of file - first entry equals zero) 

1 Number of records in DL 

2 Number of records in TL 

3 Font set number (negative implies default font set) 

4.4. Font Directory TFD1 fOptionall 

Entry 

C Starting ncord of FM for this font set 
(referenced from beginning of first FM) 

1 Number of records in FM 

2 Number of records in FS 

3 TTY tab for this font set 

4.5. Font Memory fFMI fOptional] 

EARS allows up to 32k of font memory for each set. This data must be in the standard 
MR LI format for I he RCG. The first word of FM is special and must always be #20200. 
No checks are made on this data so beware! 
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4.6. Font Specification fFSl ["Optional! 

This array allows the user to properly identify 128 charactrers in each of 16 fonts. Each 
character requires four rlements. 

Entry 

character alignment (zero implies 
special character— i.e., undef ned 
or blank) 

1 space 

2 widt i-l(lOMSH) and height- 1(6LSB) 

3 height-l(MSB) and font address(15LSB) 
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4.7. Document Directory f"DD1 
This; is a single 256 word record. 
Entry 

general password (31415) 
[replaced by first sector in core J 

1 total number of records in this tile 

2 number of pages 

3 number of copies 

4 font set used on last page (same default 
conventions as used in PD) 

5 starting record of last page 

6 length of last page DL 

7 length of last page TL 
length of PD 

11 length of FD 

12 left margin ** -1 implies use of default values 

13 bottom margin * All values ignored 

14 bits/inch * unless special password is used. 

15 lines/inch * 

16 maximum number * 
of scan lines ** 

17 special password (default is zero) 
20 ** 

to * reserved for PUB 
23 ** 



The following entries are printed on the break 
page between files. 

20Gg ID string terminated by EOL (32g words) 

232{» Creator terminated by EOL (20g words) 



252g Creation date terminated by EOL 
(24g words) 



4.8. Disclaimer 



It is clear that the preceding file definition is not complete (e.g., the format of FM 
is not given and the exact definitions for FS are not given). '1 his is intentional since most 
users do not need to know the messy details. If you need these details, come talk to me. 
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5. EARS FONT FILES 



There are five types of font files which are used either directly or indirectly by the 
EARS system . 



5 .1. .CU rCarnegie University! Font Files 

The font compressor uses .CU files as input and creates .EP, .EL and .ES files. 

Record (2 words) 

MH (Maximum height of character matrix in bits') 

1 MW (Maximum width of character matrix in 16-oit words) 

Record 1 (1 record per character 2 + MH * MW words) 

Ascii code for character 

1 Width of this character in bits 

The remaining MH*MW words contain a matrix representation of the character 
scan led left to right and top to bottom. 

5.2. .EP T EARS portrait! and .EL TEARS Landscape! Font Files 

These files are usually generated by the font compressor and contain redundant 
information that is easily usable by either a composition program or the EARS character 
generation hardware. 

Record (64 words - only 8 words are used) 

Length of record 2 in words 

1 Maximum character width in bits 

2 Maximum character height in bits 

3 Default TTY Tab in bits (usually one space) 

4 ** 

5 * Reserved for PSPOOL on MAXC 

6 * 

Record [ (1024 words - 8 entries/character) 

font address in words 

1 storage length in words 

2 character sp<ce in tits 

3 character width in bits 

4 character height in bits 

5 character baseline in bits 

6 code <0; MR LI coding 
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=0; special character 

(blank or undefined) 

>0; matrix coding 
height in bytes 

character alignment in bits - i.e. the same as 
baseline in .EP but equals the distance from 
top of matrix to bottom of ink in .EL 



Record 2 (font storage) 
FM data in MR LI format 



Record 3 (512 words - Font Specification Table 
- 4 entries/character) 

Alignment (13 MSB) and Code (3LSE5) 

Alignment two's complement 
Matrix bit 13 
End of page bit 14 
Not end of line bit 15 

1 Space in bits 

2 Width -1 in bits (10 MS3) and 
heieht-1 in bytes (6 LSB) 

3 LSB of height- 1 (MSB) and 
font address in words (15 LSB) 



5.3. ,ES TEARS specification] 

This is a text file output by the font compresser which gives detailed information 
s bout each character in the font. 



5.4. .EM fEARS Multiple] font file 

This file contains up to sixteen fonts. It is constructed from .EP and .EL files and 
is equivalent to the FM and FS entries in an .EB or .EARS file. An .ED (EAnRS 
directory) file is created simultaneously with an .EM file. The .ED file is discussed in the 
next section and is a small directory into the .EM file. 

Record (up to 32k words long - padded to 
be a multiple of 256 words) 
Word of this ccord is always #20200. The 
rest of the record is MR LI data copies from the 
second record of selected .EP and .EL files. 

Record 1 



For Xerox Internal Use Only — April 29, 1978 
EARS, GEARS, SEARS June 21, 1977 86 



This record is a directory or specification for the font data in record of this file. 
Each character is specified by four numbers as follows: 

Alignment (13 MSB) and Code (3 LSB) 

1 Space n bits 

2 Width-1 in bits (10MSB) and 
heigh t-1 h bytes (6 LSB) 

3 LSB of height- 1 (MSB) and font address 
in words (15 LSB) 

N >te that this data may be copied directly from record 3 of an appropriate .EP or 
EL file with the exception that each font address entry must be relocated to point to the 
proper data i -•, record 0. The first 128 characters of this record represent characters 0-127 
in font 0. The next 128 characters represent characters 0-127 in font 1. Up to 16 fonts 
may be included provided record does not exceed 32k words. 



5.5. .ED TEARS Directory] file 

This is a small file that is a directory for a .EM file and is used by GEARS. It is 
always 260 word; long of which the first four words are a header and the remaining are 
allocated 16 words per font. Unused space should be zero'd. 

Header 

Number of fonts in font set 

1 Number of 256 word records in FM 

2 Number of 256 word records in FS 

3 Default TTY Tab in bits 

Font Data 

Number of characters in font name 

1 Maximum width in bits 

2 Maxim.im height in bits 

3 TTY tab in bits 

4-17 BCPL string containing font name 
(unused bytes should contain nulls) 
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ListSyrns - a subsystem for listing Syms files 



The ListSyrns subsystem takes a Syms file (produced by BLDR) and converts it to a 
useful human-readable form. ListSyrns produces a file with several parts: 

A listing of the space occupied by each binary output file (.Run or .BB). 

A listing similar to the listing optionally produced by BLDR, i.e. a list, sorted by 
BR file and location within the file, of all static symbols defined, with an indication 
as to whether the symbol is external and whether it is a procedure, label, or static 
variable. 

A list of all statics in alphabetic order, accompanied by the name of the BR file 
in whici each one is defined and (optionally) a list of all the BR files in which each 
is used. 

A list similar to the preceding, but listing the statics for each file separately, and 
only listing statics declared external (i.e. accessible from other files). 

A concordance of undefined externals: for each BR file which references 
undefined externals, it lists those externals in alphabetic order under the file name. 

One invokes ListSyrns as follows: 
>ListSyms inputfile outputfile 
Inputfile will normally be something.Syms: if it has no extension, ListSyrns will supply 
.Syms. Outputfile may be omitted, in which case ListSyrns will take inputfile (shorn of 
extension if any) and append .BZ to form the output file name. 

ListSyrns accepts 7 switches, all global: 

/A produces the alphabetic listing 

/F produces a file-by-file alphabetic listing with cross-reference 

/N produces the numeric (file-by-file) listing 

/O produces only the listing of the binary file sizes 

/S includes static variables.'which are normally omitted 

/U produces the listing of undefined externals 

/X produces the alphabetic listing with cross-reference 
The switches may be either upper or lower case, and /S is independent of the other switches. 
If none of /A, /F, /N, /O, /U, or /X appears, you will get the /A, /N, and /U listings but 
no cross-reference. 

ListSyrns starts by printing a message of the form 

ListSyrns of [date] -- [inputfile] -> [outputfile] 
If ListSyrns completes normally, it will print a message of the form 

12345b characters written on outputfile 
ListSyrns produces a variety of error messages. Currently these are: 

[filename] does not exist 
indicates ListSyrns was unable to open the Syms file. 

Syms file too big 
indicates insufficient room for reading the Syms file. ListSyrns aborts. 

Can't open [filename] 
ListSyrns was unaole to open the outputfile or one of the BR files required for /U or /X. 
In the former case, ListSyrns aborts; in the latter, it continues. 

[filename] is not a proper BR file 
One of the BR files mentioned in the Syms file does not have the proper format. ListSyrns 
ignores the file and continues. 

[filename] is too big to process 
One of the BR files was too big to read in. ListSyrns ignores it and continues. 

Too many BR files 
There were too many BR files to process in the available memory. ListSyrns aborts. 

No room for bit table 
There was not enough room to hold the bit table used for /U or /X (or /A if any 
undefined symbols were present). ListSyrns aborts. 
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ListSyms is quite fast: it processes BRAVO.Syms in about 20 seconds, and a typical 
modest program takes less than 10 seconds. 
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MailCheck 



This simple subsystem attempts to check for mail for a user at. some other host (e.g. Maxc) 
via the Ethernet. It displays one of the following messages: 

? This Alto has no Ethernet interface! 

? Can't find a host named '<host>': <error message> 

? No response from <host> 

? <user> not valid user at <host>: <error message> 

? Error: <pup error message > 

New mail for <user> on <host>: <date> <sender> 

No new mail for <user> on <host> 

Various options can be controlled by switches and/or by an entry in your User.Cm. 

Valid switches are: 

/l Check mail on Maxcl (default). 

/2 Check mail on Maxc2. 

<host>/H Check mail on <host>. 

<user>/U Check mail for <user> (default is the user name obtained from the Alto 

operating system). 
/R It there is new mail, execute a command line when MailCheck exits. The 

command line defaults to "@READMAIL.CM@", i.e. to execute the contents 

of the file READMAIL.CM as a command, but this can be changed in the 

User.Cm as outlined below. 

In addition, if there may be a section in your User.Cm labeled [MAILCHECK] with the 

following possible entries': 

HOST: <host> Sets the default host to check. 

USER: <user> Sets the default username to check. 

NEWMAIL: <string> Sets the command line to be executed if there is new mail. Within the 

command line, the host name is substituted for "@H" and the user 
name for "@U"; to put an "@" in the command line it is neccessary 
to put two in the string. 

For example, you might add the section: 
[MAILCHECK] 
HOST: Maxc2 
NEWMAIL: CHAT @H MSG.DO/D 

Where MSG.DO is a file on your alto disk which contains "MSG<return>". 

One useful option is to put Mailcheck.Run inside the eventBooted section of your 
USER.CM, so that Mailcheck will be run whenever you boot, e.g. 

[EXECUTIVE] 

eventBooted: Mailcheck.Run // eventBooted 
eventRFC: FTP/QK //eventRFC 
evenlClockWrong: SetTime // even tClock Wrong 

Updates: As of March 1978, Mailcheck no longer does a SetTime 
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Mu: AltD Microassembler 



This document describes the source language and operation of Mu, the Alto microcode 
assembler. Mu is downward compatible with Debal, the original Alto assembler/debugger, 
but has a number of additional features. Mu is implemented in BCPL, and runs on the 
Alto. 



1. The source language 

An Alto microprogram consists of a number of statements and comments. Statements are 
terminated by semicolons, and everything between the semicolon and the next Return is 
tre; ted as a comment. Statements can thus span several text lines (the current limit is 500 
characters). All other control characters and blanks are ignored. Bravo formatting is also 
ignored. 

Statements are of four basic types: include statements, declarations, address predefinitions, 
and executable code. The syntax and semantics of these constructs is as follows: 

1.1. Include Statements 



Include statements have the form: 

# filename; 

They cause the contents of the specified file to replace the include statement. Nesting to 
three levels is allowed. 

1.2. Declarations 

Declinations are of three types: symbol definitions, constant definitions, and R memory 
names. 

1.2.1. Symbol Definitions 
Symbol definitions have the form: 

$name$Ln^,n2,n3; 

The symbol "name" is defined, with values nj, n? and 113. There is a standard package of 
symbols for the Alto (AltoConstsxx.Mu, where xx is the current microcode version) which 
should be 'included' at the beginning of every source program. For those who must add 
symbol definitions, the interpretation of the n's is given in the appendix. 

1.2.2. Constant declarations 
Normal constants are declared thus: 

$name$n; 
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This declares a 16 bit unsigned constant with value n. The assembler assigns the constant to 
the first free location in the constant memory, unless trie value has appeared before under 
another name in which case the value of the name is the address of the previously declared 
constant. 

An alternative constant definition is used for mask constants which have a specified bus 
source field (recall that the constant memory address is the concatination of the rselect and 
bus source fields of the microinstruction). The syntax is: 

$name$Mn:v; 4<n<7, 0<v<2**16 

N specifies the desired bus source value, v is the constant value. 



1.2.3. R Memory declarations 

R memory names are defined with: 

$name$Rn; 0<n<40B 
(100B if your Alto has a RAM beard, as most do) 

An R location may have several names. 

1.3. Address predefinitions 

Address predefinitions al cvv groups of instructions to be placed in specified locations in the 
control memory, as is required by the OR branching scheme used in the Alto. Their syntax 
is: 

!n, k, nameQ, name^, name2, ... , namek-1; 

This declaration caises a block of k consecutive locations to be allocated in the instruction 
memory, and the names assigned to them, n defines the location of the block, in that if L 
is the address of the last location of the block, L and n = n. Usually, n will be 2**p-l for 
some small p. For example, if the predefinition 

!3, 4, fooO, fool, foo2, foo3; 

is encountered in the source text before any executable statements, the labels foo0-foo3 will 
be assigned to control memory locations 0-3. If there are too few names, they are assigned 
to the Tow addresses in the block. If there are too many, they are discarded, and an error is 
indicated. If there are missing labels, e.g. "foo0„foo2,; ', the" locations remain available for 
the normal instruction allocation process. A predefinition must be the first mention of the 
name in the source text (forward references or labels encountered before a predefinition of 
a given name cause an error when the predefinition is encountered.) 

A more general variant of the predefinition facility is available. The syntax is: 

%mask2, maskl, in it, Lj, L2, ... L n ; 

The effect of this is to find a block of instructions starting at. location P, where P and 
maskl = ink, and assign the L's to 'successive' locations under mask2. For example: 

%1, 1, 0, xO, xl; 

would force xO to an even instruction, xl to odd (the normal predefinition for most 
branches). 
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%360, 377, 17, LO, LI, ... L15; 

Would place LO at xxl7, LI at xx37, L2 at xx57, etc. 

As before, if there are unused slots (e.g., 'L12„L14') they are available for reassignment, and 
MU complains if there are too many labels for the block. 

1.4. Executable statements 



Executable code statements consist of an optional label followed by a number of clauses 
separated by commas, and terminated with a semi-colon 

label: clause, clause, clause, ...; 

If a label has been predefined, the instruction is placed at the control memory locaion 
reserved for it. Otherwise, it is assigned to the lowest unused location. 

Clauses are of three types: gotos, nondata functions, and assignments. 

Goto 

Goto clauses are of the form '.-label', and cause the value of the label to be assembled 
into the Next field of the instruction. If the label is undefined, a chain of forward 
references is constructed which will be fixed up when the svmbol is encountered as a 
label. 

Nondata Functions 

Nondata functions must be defined (by a literal symbol definition) before being 
encountered in a code clause. This type of cla ise assembles into the Fl, 2, or 3 fields, 
and represents either a branch condition or a control function (e.g. BUS=0, TASK). 

Data transfers (assignments) 

All data transfers are specified by assignments of the form: 

dest]^<- dest2<- ... ^-source 

This type of clause is assembled by lookirg up the destinations, checking their legality, 
and making the field assignments implied by the symbol types. Each destination 
imposes definitional requirements on the source (e.g., ALU output must be defined, 
Bus must be defined). These requirements must be satisfied by the source in order for 
the statement to be legal. 

When the source is encountered, it is looked up in the symbol table. If it is legal and 
satisfies the definitional requirements imposed by the destinations, the necessary field 
assignments are made, and processing continues. If the entire source defines the Bus, 
and the only remaining requirement is that the ALU output must be defined (e.g., 
L«-MD), the ALUF field is set to (ALU output = Bus), and processing continues. 

If neither of the above conditions holds, the source can legally be only a bus source 
concatenated with an ALU function. The :ource token is repeatedly broken into two 
substrings, and each is looked up in the symbol table. If two substrings can be found 
which saiisfy the requirements, the field assignments implied by both are made; 
otherwise, an error is generated. This method of evaluation is simple, but it has 
pitfalls. For instance, L<-2+T is legal (providing that the constant "2" has been 
defined) tut L<-T+2 is not (the Bus operand must always be on the left). .Note that 
'L<-foo+T+r specifies a bus source of 'too' and an ALU function of '+T+1'. 
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CAVEAT: The T register may be loaded from either the Bus or the output of the 
ALU, depending en the ALU function. The assembler does not check to see whether 
an assignment of the form T<-ALU' specifies an ALU function that actually loads T 
from trie ALU. For example, the clause 'L<-T<-MD-T' is accepted, but its effect is to 
load T directly from MD. If this is what you intend, it makes matters clearer if you 
write 'L<-MD-T, T<-MD'; if it is not what you intend, you are in trouble. Beware! 

The constant "0" is special, in that when one or more clauses in a statement require 
that the bus be 0, generation of the constant is deferred until the end of the 
statement. At that point, if any clause has caused the R memory to be loaded, the 
constant is not used, since the hardware forces the bus to in this case. 

The destination "SINK" allows a clause to specify a bus source without specification 
of a destination. It is useful, for example, in constructs of the form 'SINK<-AC0, 
BUS=0\ which puts ACO on the bus to be tested by the nondata function 'BUS=0\ 
Ydu can also write things like 'SINK«-mask constant, L«-DISP XOR T', which will 
cause the value of D1SP to be anded on the bus with the mask constant. 



2 . Operation 

The assembler is invoked with: 

MU/global-switches sourcefile listfile/L binfile/B statfile/S 

Legal globa switches are: 

/L produce a listing file 

/D debug mode 

/M do not produce a binary file (overridden by binfile/B) 

If listfile/L is absent but the /L global switch is set, listing output will be sent to 
sourcefile.LS. 

If 'ainfile/B is absent, binary output is sent to sourcefile.MB. 

If st;itfile/S is absent, statistics for the assembled program are appended to the listing file if 
there is on<; otherwise, no statistics are generated. The default extension for a /S file is 
'.Stats'. 

The default extension for sourcefile is '.Mu'. 

Error messages will be sent to the listing file if one has been specified, unless debug mode 
has be;n seL In debug mode, errors are sent to the system display area, and a pause occurs 
at at every error (and at certain other times). Typing any character proceeds. 

if no listing file has been requested, debug mode is set independent of the global switch. 

3. Output file 

The assembler produceds Micro format binary output. The string names of the two 
memories specified in the file are CONSTANT and INSTRUCTION. Only defined locations 
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in these memories are output. Micro format is compatible with the PRom blowing program, 
the RamLoad program, and the PackMu/LoadRam software. Note that the instruction 
rnerrory specified in the binary file does not include the 3 bit F3 field, which exists only in 
the debugging RAM. 



4. Listing file 

The listing file contains: 

1.) All error messages (unless debug mode is set) 

2.) A listing of all unused but predefined locations and unresolved forward references. 

3.) Two listings of the contents of the constant memory, the first sorted by address 
and ihe second by value. 

4.) A listing of the names assigned to the R memory 

5.) A listing of the object and source code (with comments and declarations removed. 
The 35 bit instruction is printed out in the following order: 

Lo- ration: RSel, ALUF, BS, Fl, F2, LoadL, LoadT, F3 

6.) The microprogram statistics (unless sent to a separate file). 
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Appendix I: Literal symbol definitions 



The value of a symbol is a 3 word quantity. The first word contains a type (6 bits) and a 
value (10 bits) which detemines the interpretation of the symbol in all cases except when it 
is encountered as the source in a data transfer clause (assignment). The second word 
contains the type and value used in this case. 

The third word contains bits specifying the definitional requirements and source attributes 
applied when the symbol is encountered in an assignment. The definitional requirements 
are represented by single bits, where zero means 'must be defined' and one means 'don't 
care'. 



(destination-imposed requirements) 
ti 

(Source attributes) 



Bit 0: if L output must be defined 
Bit 1: if BUS must be defined 
Bit 2: if ALU output must be defined 
Bits 3-7: Unused (?) 
Bit 8: L is defined 
Bit 9: Bus is defined 
Bit 10: ALU output is defined 
Bit 14: ALU output is defined 
if BUS is defined 

Assignment processing proceeds by ANDing together the attribute words for all the 
destinations. The result contains zeroes in bits 0-2 for things that must b3 defined and 
ones elsewhere. 

When the source token is encountered, if it is a defined symbol it is tested by checking the 
definitional requirements of the destinations against the corresponding attributes in the 
source. If all destination requirements are satisfied, the clause is complete. If the only 
unsatisfied requirement is ALU definition, and if the Bus is defined, the ALU function is 
set to gate the bus through (thereby defining the ALU), and the clause is complete. If this 
doesn't work, or the source token is not a defined symbol, the source string is dismembered 
in a search for two substrings, the first of which defines the Bus (bit 9), and the second of 
which defines the ALU output if the Bus is defined (bit 14). If two substrings are found, 
the implied assignments are made, and the clause is complete. Otherwise, an error is 
indicated. 

The symbol type(s) determine the fields to be set in the microinstruction: Some types are 
legal only as an isolated clause, some are legal only as the source or destination in an 
assignment. The currently defined types are: 



Type: 



Legal as: 



Illegal 


never 




1 Undefined address 


address 




2 Defined address 


address 


Next 


3 R location*- 


destination 


RSel 


4 *-R location 


source 


RSel 


5 ^-Constant 


source 


RSel, BS 


6 Bus source 


source 


BS 


7 Non-data Fl 


clause 


Fl 


10 Fl*- 


destination 


Fl 


11 *-L defining Fl 

12 Non-data F2 


source 


Fl 


clause 


F2 


13 F2*- 


c estination 


F2 


14 <-Data F2 


source 


F2 



Instruction Field Side Effects: 
Receiving Value: 



Defines Bus to be 



(*-L LSH 1, etc.) 



BS*-1, RSEL<-0 
(<-DNS, -ACDEST} 
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15 


Data F2<- 


desti nation 


F2 


BS«-0, RSEL<-0 
(ACDEST<-, ACSOURCE*) 


16 


END 


clause 


- 


Not used by Mu. 


17 


<-L 


source 


- 




20 


L<- 


destination 


LoadL 




21 


Non-data F3 


clause 


F3 




22 


F3<- 


destination 


F3 




23 


<-F3 


source 


F3 




24 


«-ALU functions 


source 


ALUF 




25 


T«- 


destination 


LoadT 




26 


<-T 


source 


ALUF 


ALUF<-1 


27 


No longer used 








30 


Predefined address 








31 


<-LMRSH, «-LMLSH 


source 






32 


<-Mask constant 


source 






3:.. 


<-F2 


source 


F2 


BS<-2 


34 


<-Fl 


source 


Fl 


BS<-2 


35 


XMAR<- 


destination 


Fl, F2 


Fl<-1, F2<-6 



The current symbol definitions are contained in file AltoConsts23.Mu. 



5. Revision History 



October 24, 1974 

'%' predefinition facility added. 

March 4, 1975 

This version has changed from previous releases in that the .BM file contains micro format 
type 5 blocks which contain address symbols for the constant, instruction, and R memories. 
Programs which read these files will be expected to deal with this type of block. 

October 11, 1977 

Bugs fixed: garbage in listing if statement too long; occasionally scrambled R-register 
listings; premature termination at the end of 'insert' files. 

Features: longer statement buffer (500 characters); symbol type 35 for XMAR«-; '.Stats' file 
generated conditionally; checks for loading S-register from shifter; reports length in octal 
and decimal; strips Bravo formatting. 

March 25, 19/8 

Bug fixed: leaving the semicolon off the end of a predefinition yielded erroneous results 
with no error message. 

Features: listing file contains constants sorted by value as well as by address; source filename 
extension defaults to '.Mu'. 
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Network Executive 



NetExec is an Alto command processor for invoking certain subsystems via the Ethernet 
without using the local disk. It is useful for rebuilding a smashed disk and for loading 
diagnostic programs when the disk is sick. Its user interface is intentionally similar to the 
standard Alto Executive. 

The program is invoked by holding down the <backspace> and <quote> keys while pressing 
the boot button. You must continue to hold the keys down uni.il a small square appears in 
the middle of the screen, then yau can let go. NetExec and all of the programs invoked by 
it are boot-format files kept by 'boot-servers' -- programs which implement the Alto boot 
protocol. Most gateways and some other programs (such as Peek) contain boot-servers. 

When the NetExec arrives, it displays a ">" and blinks its cursor to indicate that it is ready 
for commands from the user. In parallel with this it displays a pair of lines near the top 
of the screen with its name and version number, a digital clock, and the machines 
internetwork address. 

Typing "?" causes the NetExec to display a list of the boot-files it knows how to invoke. 
NetExec builds this list by probing the network for boot servers and asking them what boot 
files they are willing to give out. There are also some built-in functions which are listed by 
"?" as if they were boot files: 

Probe Causes NetExec to probe the network looking for boot servers. If it 

discovers any new ones, it will add the new boot files to its list. This 
is done once automatically when NetExec starts. 

SetTime Causes NetExec to probe the network looking for a time server. If it 

discovers one, it sets the Alto's clock from it. This is done once 
automatically when NetExec starts. 

Keys Prompts you for a boot file name and tells you the key combination 

which will boot it directly. 

Host Prompts you for a boot file name and tells you which Ethernet host 

NetExec will get the file from. 

Quit Boots DMT 

In the future, common subsytems should be stored in a few places throughout the network, 
not on every local disk; perhaps the local disk can be eliminated entirely. Doing so requires 
a much better integration of network and OS facilites than currently exists. The NetExec 
described here is not intended to do this. There are several limitations in the current 
implementation: 

1) Most boot-files are core images and so are quite large. Typical boot- 
servers have space for about 15 core-image files. 

2) Boot-files are not properly hooked into the local disk. Programs 
which use overlays or keep internal file pointers (such as Bravo and 
DDS) will not work. 

:<) Boot-servers typically run in machines with some other primary 
purpose, such as gateways, and must not consume too many resources. 
As a result, booting is slow and only one machine can be served at a 
time. 
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OEDIT 



The OEDIT program is for looking at and modifying Alto files in octal. Call it with 
OEDIT fl f2 ... where the f's are the names of the files you want to look at. It will 
display the contents of the corresponding words of all the files on the same line. There is a 
limit of four files which can be looked at simultaneously. If you want to be able to 
modify the first file, use the /W switch on the OEDIT command. If you don't use this 
switch, OEDIT will request confirmation before letting you write into any of the files. 

When it starts, the program computes the length (in bytes) of all the files. For large files 
this can take upwards of 15 seconds, so don't be alarmed by the delay. 

After typing the lengths, OEDIT waits for commands: 

n/ show location n of each file 

If show the next location of each file 

t show the previous location of each file 

cr show the current location again 

n! show locations n to n+37 of each file 

> show the next 40 locations of each file 

< show the previous 40 locations of ech file 

nF beginning at current location in the first file, 

find a word containing n, show it and its address 
Q quit 

The If, t, <, >, and cr commands can be preceded by a number which is written into the 
current location of the first file. 

All numbers are octal. All addresses are word addresses (even though the lengths are shown 
in bytes.) Oedit shows each value as an octal number, two octal bytes, and two Ascii 
characters. 
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Alto microcode overlays 



Large systems which use the Alto control RAM, such as ByteLisp and Mesa, 
inevitably want to put more instructions in the RAM than will fit. When this happens, the 
system implemcntors can choose either to implement the additional functions in software, or 
to change the contents of the RAM dynamically. The package described here provides for 
relatively cheap dynamic overlaying of the RAM. The overlay regime can be very simple 
(just one overlay in RAM at a time) or complex (a nested allocation scheme) with no 
changes in the swapper or the overlays themselves. 

Users of this package must, of course, still decide when loading microcode is 
preferable to falling back into Nova code. In terms of space, one microinstruction does 
about 2/3 as much work as a Nova instruction, and takes 32 bits rather than 16, so 
(overlaid) microcode takes about 3 times as much core space for equivalent tasks. The 
package presented here imposes an additional space overhead which may amount to as much 
as 2 * the square of the number of overlays. In terms of speed, loading a microinstruction 
takes about as long as executing a Nova instruction, and the package described here adds an 
additional time roughly equal to 1 Nova instruction for each overlay each time a new 
overlay must be loaded, so for totally straight-line code the net execution time favors Nova 
implementation by about a factor of 2 (i.e. to break even, a given overlay must be executed 
at least twice). However, microcode has easy access to the state information stored in the 
processor's R registers, while Nova code does not (unless it. can all be passed through the 
AC's), sc this may make microcode execution preferable even in the case of straight-line 
code executed only once. 

1. How to use it 

Using microcode overlays requires three steps that differ from normal use of the 
RAM. The Mu assembly process is different; the Oram program must be run to construct 
the data structures necessary for the swapper; and a small amount of extra initialization is 
required at runtime. 

The first step in constructing overlayable microcode is to decide how to break up 
one's microcode into overlays and to identify the entry points to each overlay. (One overlay 
may have more than one entry point.) The microcode sources must be broken up into files: 
a main file that includes all the resident code, plus predefinitions (but no code) for all 
entry points of all overlays; an initialization file (to be described in a moment) that 
supplies dummy code for all entry points; and files for the individual overlays. 

The main file must include the following code at the beginning: 

!0,l,zero; Required by the swapper 

$ramvec2$Rnn; An S register for the base of the overlay table 

[other predefinitions, symbol defs, constants, registers, etc.] 

#swapper.mu; The swapper 

This code must occur at the beginning of the main file because the swapper's entry point 
(label "swapper") must be predefined as location 1000 in the RAM. 

The initialization file must have the following form: 

#main.mu; (or whatever the main file is called) 

entO: T «- 0, :swapper; 
entl: T <- 1, swapper; 
enr.2: T <- 2, swapper; 
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2nt3: T <- 3, :swapper; 

and so on for all the entry points. (EntO, etc. should be replaced by the names of the entry 
points, of course.) 

Since microcode is not relocatable in the RAM, all decisions about what overlays can 
be co-resident must be made at assembly time. 

After assembling the dummy file and each leaf overlay file with Mu in the usual 
way, run the Oram subsystem as follows: 

>Oram xx.BR init.MB ovl.MB ... ovm.MB 
where xx.BR is the BR file on which Oram will write the overlay tables, init.MB is the 
result of assembling the initialization file, and ovl.MB through ovm.MB are the results of 
assembling the leaf overlay files. If all goes well, Oram will produce a variety of messages 
ending with 

nnn words written on xx.BR 
and return to the Executive. Oram also writes all its messages on a file called Oram.Lst. 

When you load your program with Bldr, you must include the file xx.BR produced 
by Oram. The data in this file, unlike the initial RAM image produced by PackMu, is 
required throughout the running of your program. You must also load the RWREG library 
package to obtain the WriteReg procedure used below, but this is only needed during 
initialization. 

When loading the RAM during initialization, your program must include the 
following code: 

external [ MCbase; MCtop ] // defined in xx.BR 

if (MCbase&l) ne then 
[ let len = @MCtop 

McveBlock(MCtop-len-l, MCtop-len, len) 

MCbase = MCbase-1 



Write 



l;eReg(nn, MCbase-2) 

where nil is the register number in the definition of ramvec2 in the main file. 

2. Design details 

In the RAM, the entry instructions of each overlay are all in the permanently 
resident code. If the overlay is present, the entry instruction is just the first instruction of 
its code; in this case we say the entry instruction is "valid". If the overlay is absent, the 
entry instruction loads T with the entry number and branches to the swapper (the entry 
instruction is "invalid"). Thus when an overlay is loaded, the entry instructions of all 
overlays it overlaps must be invalidated. The chief advantage of this approach is that there 
is absolutely no time overhead if the overlay is already in the RAM, so it is feasible to 
overlay very short sequences (15 instructions, say). 

There is just one global data structure (in core) that describes the overlay structure: a 
table indexed by 2 * entry number which points to overlay descriptions, described in the 
next paragraph, and also specifies where to start execution after the overlay is loaded. (This 
arrangement permits a single overlay to have multiple entry points.) The origin of this 
table is the only thing known to the swapper. 

The description of an overlay (in core) must begin at an even location, and has two 
parts: 

1) An invalidation table which specifies how to overwrite entry instructions. Each 
entry in this table is a 2-word object: the first word is a RAM address, the second word is 
the upper half of the microinstruction to write there (the lower half always being 
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"BUS<-constant, Load T, branch to swapper"). The last entry is flagged by having bit of 
the RAM address set. 

2) A. sequence of instruction blocks. Each block begins with a 2-word header 
(100000b+RAM address, 0). The following data are a sequence of instructions where each 
instruction's NEXT field specifies where to load the following one: this sequencing scheme 
eventually requires the block to end. This sequence is terminated by a final clock consisting 
of two zero words. 

The swapper is a routine in the resident microcode which expects an entry number 
in T, loads the appropriate overlay, and branches to the entry. It must fetch the overlay's 
description from core and then do the following things: 

1) Invalidate the entry instructions of all overlays with which the one being loaded 
conflicts. 

2) Load the code, which must include the entry instructions specified as being newly 
valid; 

3) Branch to the code. The initial RAM load must have all entry instructions invalid. 

3. Mu/Bldr interface 

The third design issue is how best to get the necessary data structures incorporated 
into Bcpl/Nova programs. It turns out that it is possible to support nested overlays with no 
changes to Mu. For example, suppose that the main body of the microcode is M, and that 
we have three overlays: X (entry point XI), which takes all the overlay space, and Y (entry 
points Yl and Y2) and Z (entry point Zl), which will both fit at the same time. Assemble 
the following configurations with Mu: M+X, M+Y, and M+Y+Z. Then an overlay 
preparation program, Oram, can compute all the necessary tables and produce a .BR file that 
can be loaded with the user's program. 

It is necessary to be a little careful to arrange that the entry instructions fall in the 
same locations in all assemblies. Furthermore, if it is desired that one routine occupy a 
subset of the RAM locations of another, they must have the same configuration of 
predefinitions (and, of course, appear at the same place in the assembly sequence). Here is a 
sketch for the example: 

M contains (somewhere): 
!0,1,X1; 
!0,1,Y1; 
!0,1,Y2; 
!0,1,Z1; 

X contains: 

XI: [code for X] 

Y contains: 

Yl: [code for YJ 

Y2: [more, code tor Y] 

Z contains: 

Zl: [code for Z] 

In general, some of the predefinitions could be omitted if the entry addresses were to be 
predefined earlier, for example if they were entries in some kind of opcode dispatch. In 
addition, there must be another file W which is assembled with M to produce the initial 
RAM load: 

W contains: 

XI: T <- 0, swapper; 

Yl: T <- 1, swapper; 

Y2: T <- 2, swapper; 

Zl: T <- 3, swapper; 
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The pointer table would have the appearance 

Xdesc; XI; 

Yctesc; Yl; 

Ydesc; Y2; 

Zdesc; Zl; 
and the individual descriptions would be as follows: 
Xdesc: Yl; invalidate Y and Z 

BUS<-1 (hi part); 

Y2; 

BUS<-2 (hi part); 

#100000+Z1; 

BUS*- 3 (hi part); 

[code for X] 

0; 

Ydesc: #100000+X1; invalidate X 
BUS<-0 (hi part); 
[code for V] 

0; 
Zdesc: #100000+X1; invalidate X 
BUS<-0 (hi part); 
[code for Zj 

0; 
Fortunately, given the .MB files, the Oram subsystem can construct all the tables itself. 
Oram assumes that any instruction in the base file (W) which branches to the swapper is an 
entry instruction. 
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PackMu, Rpram, ReadPram 

These two subsystems and one library package make it easy for Alto programs which 
use the RAM to check the constant memory and load the RAM as part of their 
initialization. The first subsystem, PackMu, takes the output of Mu (a .MB file) and 
converts it to a "packed RAM image" which is easy to load. The second subsystem, Rpram, 
reads a packed RAM image, checks the constant memory, and loads the RAM (i.e., it is a 
microcode loader). This function is also available through a pair of library routines 
ReadPackedRAM and LoadPackedRAM (available on a file called ReadPram. bcpl). 

A packed RAM image is a .BR file containing 4401b words of data. The first word 
is ignored. The next 400b words are the desired contents of the constant memory: a zero 
word (which Mu cannot generate) means "don't care". Constant is reserved for a version 
number, to help programs check that they are getting the correct RAM contents. The 
remaining 4000b words are the contents of the RAM. Each instruction occupies two words, 
first high-order part, then low-order part, e.g. words and 1 go into RAM location 0, 
words 2 and 3 into RAM location 1, and so on. 

The invocation format for PackMu is 

> PackMu foo.MB foo.BR version staticname 
Foo.MB is the output from MU. Foo.BR is the file for the packed RAM image. Version 
(optional) is a RAM version number which will be written as constant in the output file; 
if omitted, i! defaults to zero. Staticname (optional) is the name for the static in foo.BR 
which will point to the RAM data; if omitted, it defaults to Ramlmage. PackMu prints out 

xxx constants, yyy instructions 
to indicate the number of constants and instructions read from foo.MB. If foo.MB is 
somehow illegal, PackMu prints 

Error: 
and an error message instead. 

The invocation format for Rpram is 

> Rpram foo.BR version 
where foo.BR is the output from PackMu. If there are any disagreements between the 
constants in foo.BR and the actual constant memory, Rpram prints 

Constant nnn is xxx, should be yyy 
for each constant that disagrees, and a summary message 

nnn constants differ 
at the end of loading (but it still loads the RAM). If version is supplied and disagrees with 
constant location in foo.BR, Rpram prints 

RamVersion in file is xxx; version expected is mmm 
If Rpram believes that foo.BR is not a file written by PackMu, it prints 

Bad RAM image 
If everything is OK, Rpram prints nothing. 

To read in a packed RAM image file from a program, use the subroutine 
ReadPackedRAM(stream, WRamV ["]). The stream argument should be a word-item input 
stream positioned at the beginning of a foo.BR file; lvRamV, if supplied, is taken as the 
address of a variable in which to store the value given by the file tor constant (i.e. the 
RAM version). ReadPackedRAM does exactly the same thing as the Rpram subsystem, 
including printing disagreement messages on the display, but instead of printing the 
summary message it just returns the number of disagreements, or -1 in the case of a bad 
RAM image file. Rpram essentially just opens foo.BR and calls ReadPackedRAM. 

Alternatively, you may wish to load the RAM image foo.BR with your program. In 
this case, use the subroutine LoadPackedRAM(staticname, lvRamV []) where staticname is 
the name you gave to PackMu. LoadPackedRAM does the same thing as ReadPackedRAM, 
except it takes the data out of memory instead of from a file. 
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Maintained notes: 

PackMu uses the library packages GP and ReadMu. 
Rpram uses the library package GP. 
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Peek Pup 



PeekPup is a small subsystem enabling one to peek at Pups going to and from a particular 
Ethernet host. It is intended as an aid in debugging new Pup software. 

PeekPup is invoked by the command 

PeekPup hostn umber filename 

where "hostn umber" is the Ethernet address (octal) of the host whose packets you want to 
spy on and "filename" is the name of a file to write the output on. The program then 
looks for packets whose Ethernet source or destination address is equal to "hostnumber", and 
buffers them in memory. For each Pup so processed, "!" is displayed on the screen. 
PeekPup terminates when any key is pressed, at which point it interprets the last 200 Pups 
received and writes the rssult on the specified file. 

The output is mostly self-explanatory. The numbers in the left margin represent a 
millisecond clock (with no particular starting value and wrapping around at 32/68). For 
each Pup, a few lines of output are generated; the information about Pups sent to the host 
being spied upon is indented further than information about Pups generated by that host. 
Pup headers are fully interpreted, and Pup contents are displayed as either text or a series of 
octal numbers representing bytes; large Pups get only the initial portion of their contents 
displayed, followed by "...". 
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Pressed it 



Pressedit is useful for combining Press files together, converting the Ears files generated by 
Pub and Bravo into Press format, selecting certain pages from a Press or Ears file, or adding 
extra fonts to a Press file. The general command format is illustrated in the following 
example: 

pressedit foo.press <- a.press b.ears 2 5 c ; press 3 to 7 9 meteor9/f 

This means "make a Press file foo.press from all pages of a.press, pages 2 and 5 of the Ears 
file b.ears, and pages 3, 4, 5, 6, 7 and 9 of c.press; add font meteor9 to the fonts defined in 
foo.press". The resulting file will be arranged in the same order as the component input 
files. 

Examples: 

To convert an Ears file foo.ears to a file foo.press in Press format: 

pressedit foo.press «• foo.ears 
To extract pages 3 and 17 from a Press file long.press, and put them in sliort.press: 

pressedit short.press «- long.press 3 17 
To extract pages 5 through 12 from foo.ears, and put them in short.press: 

pressedit short.press «- foo.ears 5 to 12 
To add fonts lo«o24 and helvetica 14 to a.press: 

pressedit a.press «- a.press logo24/f helvetical4/f 
Here the arguments on the right hand side of the arrow may be given in any order. 
To make a blank, one-page Press file containing all three faces o/TimesromanlO: 

pressedit blanktimes.press «- timesromanlO/f timesromanlOi/f timesromanlOb/f 

To append to the end of chap3. press all the Press files with names fig3-l. press, fig3-2.press, 
fig3-3. press etc: 

pressedit chap3. press *- chap3. press fig3-*.press 

Caution: when you combine files with Pressedit, try not to use different sets of fonts, or the 
same fonts in different orders. This will result in proliferation of font sets, making the 
file more bulky and creating other minor sources of inefficiency. 
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Press Print Program 



The Print program can be used to print any Press file. Simply type: 
print filel.press file2.press <return> 

If you type /s after a file name, the file will be saved on Maxc in Ears format. You 
may print more than one copy, as follows: 
print 5/c foo.press 

This will print five copies of foo.press. 

Printing is at present done via Maxc. If you are logged in to Maxc, you may print a 
Press file, 'foo.press,' on your Maxc directory by typing the following: 
ears foo.press < return > 

All of the normal subcommands, for extra copies etc., are available. 
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Alto QED Text Editor 



Alto QED provides a subset of the facilities incorporated in the original QED 
implementation, the most notable omission being facilities for line editing. 

QED is designed to run on a 64K Alto. All of the body of text being edited is maintained 
permanently in core. This makes for fairly rapid operation, but restricts the amount of text 
that can be edited to about 1500 lines of average BCPL program. The screen can display 20 
lines of text. 

Line numbers are not stored internally, but are computed by QED. Whenever text is added 
or deleted, the numbers of the lines following the alteration are changed accordingly. 

A complete list of commands in QED is as follows. Here s, f, and e are line numbers or 
expressions (see below); c is the confirm character (carriage return). The user types the 
underlined text; commands may be typed in upper or lower case. 

eAppendc The following text is added after line e. 

s,fC hangec The following text replaces lines s to f. 

s,fD eletec Lines s to f are deleted. 

JRnishc Terminates editing and returns to the operating system. 

eh sertc The following text is added before line e. 

s,fM ove a copy after ec A copy of lines s to f is placed after line e. 

s,f O verwrite old file name c Lines s to f are written onto the file which was last read 
or written. 

eRead from filenamec Text is read from file and is added after line e. 

s.f S ubstitute newc for oldc QED substitutes the new text for the old text wherever the 
old text is found within the given range. The number of substitutions is typed. 

sJTransfer after ec Lines s to f are moved after line e. 

eWrite on filenamec Lines s to f are written out onto the named file. Note that this 
command does not affect the contents of the buffer. 

s.fX change newc for oldc Similar to Substitute, but the user must confirm each 
substitution with c, otherwise the substitution is not made. The line containing 
each occurrence of the old text is printed, with the text surrounded by double 
quotes. If ctrl-0 is typed instead of c, then no further substitutions are made. 

s,f/ Lines s to f are listed on the screen. 

e= The value of expression e is typed on the screen. 

QED allows expressions to be used in place of line numbers: thus e, s and f may be any one 
of the following: 

a line r umber 

the symbol $, meaning the last line in the buffer; 

a period, meaning the current line; 

;text; or 'text', meaning the next line following the current 
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one on which the given text occurs; 
-- :text:, meaning the next line starting with the given text; 
— an expression formed by combining the above, using the 

symbols + or space for addition, - for subtraction. 

If s is omii.ted, QED assumes that the first line was meant; if f is omitted, it assumes the 
last line; both may be omitted...thus a single comma is equivalent to 1,$, i.e. the entire 
buffer contents. In addition the user may omit line numbers altogether: most commands 
will then assume that the current line was meant with the exception of Write and Overwrite 
which assume the entire buffer; and Read and Append v/hich assume that the last line was 
meant. 

The current line changes whenever text is read in, written out, added or deleted. The 
commands Substitute, Achange and = leave the line number unchanged; all others leave it at 
the last line of input or output or last line moved, with the exception of Delete which 
leaves it at the line after the deletion. The easiest way to reset the current line to a fresh 
position is to type the new line. To type the line following the current one, type line-feed 
(LF); to type the previous one, type t. 

Td start input to QED, type QED to the operating system, and then type A to append. 
Diring input, you may erase the last character typed with Ctrl-A, the whole line with DEL 
or Ctrl-D, and retype the line being input with Ctrl-R. DEL will normally cancel any 
command being typed. Input following Append, Change and Insert is terminated with Ctrl- 
Z. 



Note: 



1. QED removes line feeds, rubouts and nulls when reading from a file, and appends a 
line feed after each line when writing to a file. 

?.. Control characters within a file are invisible. 



For Xerox Internal Use Only — April 29, 1978 
RAMLOAD April 1, 1975 110 

RAMLOAD 



RAMLOAD is a program that acts as a microcode loader, using the output of the microcode 
assembler Mu. Since there are now two types of microcode memory for the ALTO, some 
distinction must be made. Hereafer, ROM means some combination of roms on the ALTO 
control board, and add-on goodies which hang on the end of the control board like 
debuggers with 512 words of ram. RAM means the extra board with IK of ram which 
plugs into a slot in the processor. 

RAMLOAD gets its parameters from the command line and default values. If you do not 
specify a parameter, the default is used. In addition there are some global switches which 
do other useful things as explained below: 
GLOBAL SWITCHES (of the form RAMLOAD/switchlist) 

/R compare the micro binary file against the contents of the RAM and display 

differences. 
/V compare the micro binary file against the contents of the ROM and display 

differences. 
/C compare the micro binary file against the contents of the constant memory and 

display differences. 
/T Test the RAM and extra R registers by writing random numbers and then reading 

them back displaying differences and addresses. 
/O Same as /T but do not lest the R registers. 

/N Do not request Confirming <CR> for any operation. 

LOCAL SWITCHES (of the form foo/switch) 

/F use foo as the name of the micro binary file. Default is "BINFILE." 

/M use foo as the name of the instruction memory in the micro bins ry file. Default 

is "INSTRUCTION". 
/C use foo as the name of the constant memory in the micro binary file. Default is 

"CONSTANT". 
/V foo is an octal number. Use it as the boot locus vector. Bit 15 corresponds to 

task (emulator). means run task in the RAM. Default is #177777 - keep all 

tasks in ROM. 
/A loo is an octal number, representing the base address of a 5 word area in the 

RAM which RAMLOAD can use for utility purposes. Default is the top 5 words 

(#1772). See warnings below about restrictions for specific operations. 
/S loo is an octal number interpreted as the beginning address of the emulator main 

loop (START for microcode hackers). Default is the current START address, 

#20. 

Note :hat global switches /V, /C, and /T do the same things that ;V, ;C, and ;T do in 
DEBAL. RAMLOAD in effect does a ;L, and also sets the boot locus vector. The /R 
global switch was added because it was easy and people might want to see if the microcode 
got smashed after a fiasco. 

When RAMLOAD is called, it will first display what it thinks it is supposed to do as 
governed by the switches and defaults, and wait for a confirming carriage return. When 
this is received, it will attempt to open the micro binary file. If this is unsuccessful, it will 
put out a message to thf.t effect. Next, operations specified by global switches will be 
performed (If the micro binary file could not be opened, the only tests possible are /T and 
/O). If no global switches were set, the program will assume you wanted to load, and do so 
without waiting for confirmation. Loading is a three step operation in which the first step, 
setting the boot locus vector, does not require an open micro binary file. This allows a user 
to change the boot locus vector without reloading the RAM, by specifying a nonexsistant 



For Xerox Internal Use Only -- April 29, 1978 
RAMLOAD April 1, 1975 111 



file name for the micro binary file. The program will report the value the vector is set to. 
Steps two and three, unsnarling the micro binary file and loading its contents, obviously 
require an open file and will cause RAMLOAD to bomb if there is none. When the 
loading operation is complete, the number of instructions loaded, and the highest address 
will be reported ala DEBAL. Next the program will ask if you want to boot, thus moving 
the tasks specified in the boot locus vector into the newly loaded microcode in the RAM. 
If you confirm, and if you have an Ethernet board, the machine will do a software initiated 
boot. If you do not have an Ethernet, the boot will be a NOP, and a FINISH is executed. 
Hitting the boot button after the program is finished will work for those hermits who do 
not have Ethernets. 

The routine which reads the micro binary file expects the limited subset of block-types that 
DEBAL puts out. If it encounters an unusual block-type (3, 5, or 6) , it will endeavor to 
do the right thing, and continue on. When it is finished reading, if any unusual types were 
encountered, it will list how many of each it read. If the microcode was assembled using 
DEBAL, this is cause for grave doubts about the correctness of the file, since DEBAL will 
not currently generate these types. 

Where the 5 word utility area is specified can hav* profound (ie. potentially disasterous) 
effects on the machine's operation it you are currently running from the RAM. While it is 
possible to load the RAM while executing in it, this is living very dangerously. However, if 
you must, observe the following caveats: 

* if constant memory is being checked, and you are executing out of the low 256 

locations, you are dead. 

* the 5 word utility area must be specified in a place you vvill not be executing from 

during the RAMLOAD program. RAMLOAD always saves any word in RAM it 
modifies for utility purposes, and restores it when it is done, but while in use, it 
can have an arbitrary value. 

A number of things can cause fatal errors during execution. If one happens, an error 
message is written in the system display area, and the program is aborted. 
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SCAVENGER 



A subsystem for checking and correcting disk packs is available as SCAVENGER. Invoke it 
with no parameters and it will give you an opportunity to (1) change disks and (2) prevent 
it from altering your disk seriously (see below). 

The scavenger does the following: 

1. Corrects header blocks, prompting for confirmation. 

2. Corrects check sum errors, by re-writing whatever came in, prompting for 

confirmation. 

3. Discovers all well-formed files and all free pages. Any disk page (except page 0) that 

is neither free nor part of a well-formed file is considered bad. 

4. Makes the serial numbers of all well-formed files are distinct. 

5. Corrects the system's notion of what pages are free. 

6. Corrects the system's latest serial number. 

7. Corrects the directory to contain precisely the well-formed files. If a directory entry 

points into a chain of bad pages it attempts to salvage the file. If need be a 
directory is created from scratch. 

8. Links all bad, unsalvaged pages together as part of the file Garbage.S. 

9. Describes all changes to the disk in the file Scavenger Log, even those which were not 

actually performed. 

10. Corrects leader page information. Changes to leader pages should not cause alarm. 

The information there is used as a hint by various systems. 

The data in bad pages is not changed so you can attempt to reconstruct a lost file by 
suitable operations on Garbage.?, consulting ScavengerLog to interpret its contents. 

A hopelessly smashed disk may be put back in shape by the following: 

1. Invoke scavenger on a good disk and answer yes to "Do you want to change disks?" 

2. Replace the good disk with the bad one. 

3. Answer yes to "Is the new disk ready?" when the yellow ready light comes on. 

4. Answer yes to "May I alter your disk to corrct errors?" 

5. If FTP lives on your disk, the scavenger will offer to invoke it rather than retuning 

to the executive. Once you are in FrP you can receive critcal files (like 
Executive.Run or SysFont.Al) or evacuate your disk by sending files elsewhere. If 
the scavenger does not offer FTP, it is not there and you will have to do some 
more disk suffling to retreive files; i.e. invoke FTP from a good disk and change 
disks after you are in. 

You should take precautions to avoid losing vital files (such as QUICKing your disk to 
another disk pack prior to running SCAVENGER). 
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PARC information 

The following, more or less independent, procedure can be used to recover vital files that 
might have been lost during scavenging. 

1. Invoke FTP on a good disk. 

2. At an early point in the dialogue replace the good disk with the bad one and wait 

for the yellow ready light to come on. 

3. Retrieve the needed files from MAXC (Executive.Run and FTP are the minimum 

required, I think.) 

4. Quit out of FTP. 

5. Run the scavenger. It will correct the DiskDescriptor file which became inaccurate 

during this process. 
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SetTime 



This simple subsystem attempts to obtain the date and time from a time server on the 
connected Ethernet. If it is successful, it sets the date and time in the operating system and 
also displays it. If unsuccessful, it displays an error message and prompts you to type in the 
date and time. 

This subsystem intentionally has the same name as the corresponding Alto Executive 
command 'SetTime.~'. If your Alto does not know the date and time when the Executive is 
started, it executes an automatic SetTime command. If SetTime.Run exists on your disk, it 
will be run in preference to executing the Executive command "SetTime."'. 

If SetTime.Run is unsuccessful in obtaining the date and time (which is unlikely unless the 
Ethernet is broken or your Alto isn't connected), it will ask you to type in the date and 
time in the form 'day-month-year hounminute', e.g., '2--j£.n-78 19:15*. Additionally, it may 
ask you to enter the local time zone, which may be Eastern, Central, Mountain, or Pacific. 
(You may also enter '+' or '-' followed by a tune in the form 'hours:mi mites' designating 
hours west (+) or east (-) of Greenwich.) 
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Swat, a BCPL-oriented debugger 

Swat is a debuseer meant to be us:*l with the ALTO operating system. While many of its 
features are BCPL oriented, it can be used on any NOVA code program. This document 
describe; version 18 of Swat. 

1. Invocation 

Swat may be applied to any program running under the operating system after it has been 
installed (see I nstallation below). There are four ways of getting its attention: 

(1) Press the lowest, right-hand key of the ALTO keyboard, 
together with the <control> and <shift> keys at the left. 

(2) Have your program execute the cp-code 77400B. 

(3) Invoke the Resume/S command (see below). 

(4) Boot the file Dumper.Boot, normally by booting with the "DU" 
keys depressed. 

(5) Type <programname>/! to the Alto command processor. 

(6) Call the function CallSwat. Up to 2 arguments will be printed 
as BCPL strings. Thus CalISwat("No more memory") 



2 . Commands 

The command has suffix action symbols, all control characters (e.g. tC). "n" is any BCPL 
expression (see Expressions below), "$" is escape except where noted, cr" means carriage 
return, "If" means line-feed. 

2.1. Displaying cells 

ntD prints the contents of n in decimal 

ntl prints the contents of n as two 8-bit bytes 

niN prints the contents of n as a NOVA instruction 

ntO prints the contents of n in octal 

ntS prints the contents of n as a pair of characters 

ntV prints n (in octal) rather than its contents 

The last cell printed is called the open cell. tO, tD, tl, tN, or ?S alone re-prints the open 
cell in the appropriate format. IF you "wish to print out a number of cells, beginning with 
the open cell, say n$iD, n$tl, etc. This command will not change the identity of the open 
cell. 

If (tj) prints the contents of the next cell (after the open one) in the same mode. 

tW prints the cell before the open cell. 
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?A prints the cell pointed at by the open cell. 

tE treats the open call as a NOVA instruction, computes its effective address and 

prints its contents. 

1.2. Changing cells 

The contents of the open cell (if there is one) may be changed by typing an expression for 
he new /.alue followed by a cr or If. 

1.3. Running the program 

tP resumes the program, i.e. proceeds. 

ntG resumes the program at n, i.e. goes there. 

<eQ>$<£i >$...$<e n >tC calls procedure <en> with parameters <ej>,...,<e n > (n<6). If you 
wish one of the arguments to oe a BCPL-format string, merely enclose it in 
quotes. Thus Open£ile$"Com.Cm."tC will return a stream on the file. 

?U restores the user's screen. Hitting the break key brings back Swat. 

tK forces the user programs to abort. 

2.4. Break Points 



ntft sets a break at n 

tE> set a break g.t the open cell 

0$ntB deletes the break at n 

0$$tB deletes all breaks 

$$tB prints all broken locations and checks that they haven't been clobbered. 

$tP removes the current break and proceeds. 

n$tP sets a break at a BCPL return point in the stack somewhere and proceeds from 
the present break. The parameter n specifies the frame. Thus if tT typed out 
0:GOO+56 1-.HAM+5, l$tP would set a break at HAM +6 and proceed. 

2.5. Stack Study 

tT prints the current PC and all return addresses in the call stack (symbolically), 

until an inconsistency is found in the stack. After each return address is listed 
the parameters passed to the procedure that will be returned to. Thus, if you 
see an entry like "3: Findlt+4^ — (14 ] 77777 )", the procedure Findlt was; called 
with arguments 14b and -1. 

ntT prints n (or less) return addresses. 

ntF prints the parameters of the nth latest stack frame and sets the pseudo symbol 

'$" (not escape) equal to the base of that frame. If tT displayed something 
like 0:FOO+3, 1:BLETCH+10„.. Type ltF to see the parameters that were 
passed to BLETCH. $ is set to the base of BLETCH's frame. 
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>.6. Symbol table 

tV prompts to get a symbol file. Type the name of the subsystem that's running. 

(If BLDR created the file FOO it also created FOO.SYMS which gives the 
locations of all the static names. Only statics can be used in Swat.) 

11. Save/Restore 

tQ saves the current SWATEE on a file (prompts) (see below) 

tL makes a (prompted for) file the current SWATEE (see below) 

>.8. The Spy Facility 

The sry i:a \ be used to estimate where the time is going on a percentage basis. (It samples 
he PC every 30-nilliseconds). 

il) Type tX and Swat will display how much user memory it needs for the metering 
code and tables. 

i'2) Probe around to find a block of storage of the required size, and tell Swat by typing 

ntX 

where n is the first word of the block. 

i'3) Proceed to run the program. 

i4) Once Swat gets control again you can type 

$tX 

to display the results and terminate the spying activity, or 

$$tX 

to display the results so far and continue the spying. 

1.9. M i scellaneous 

$tY Will prompt for the name of a (text) file from which Swat commands should 

be taken. Reading will continue across "proceeds" from breakpoints, but will 
b2 aborted if Swat is invoked by the keyboard or by the standard break-point 
trap (77400b). 

ntR Prints out the value of an R or S register n. You must have a RAM for this 

to work, and n cannot be 37b or 77b. 

1.10. Examples 

K'OtD prints the value of X in octal, then decimal. 

?UNC+3+tN If If prints instructions 3, 4, and 5 of FUNC. 
It 07 sets location 1 to 7. 



SWAT 
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LABELtB sets a break at LABEL 

7562tB sets a break at location 7562B 

SQRT$16tC calls the (user) function SQRT (the returned value is printed) 

LABEL+3tG transfers to the third instruction after LABEL. 

OfT prints the PC 

OtF prints the parameters of the most recent call 

2tF prints the parameters of the third most recently called procedure; then 

$tO prints the saved stack pointer (FLAST) 

S+ltO prints the return address (FRET) 

S+6tO prints the first local (if the procedure has 2 parameters). 

3. Expressions 

Expressions are as in BCPL with the following exceptions 

means exclusive or 
\ means remainder 

| means lshift for positive arguments, rshift for negative 

means NOT 



A string of digits is interpreted as octal unless suffixed by a "." 

$ (not escape) is the base of the last opened stack frame (see tF above). Initially it is tlv; 
last frame. 

. is the last opened cell 

.PC is the address (sic) of the PC 

.AC1, AC3 are the addresses of the accumulators 

.CRY is the address of the carry bit 

No function calls in expressions. 

No relational operators (e.g. EQ) 

No conditional expressions 

No lv operation 
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3.1. Examples 

.-ltO prints the ce 1 before the currently open cell. 

.+ltO is like line-feed. 

.AC It 06 sets AC1 to ('» 

.PCt072 

tP is like 72tG 

.PCtO If If If If prints the PC and the AC's 

The conventions for expression evaluation are not truly BCPL-like. "FtO" will print the 
first instruction of F if BLDR thought it was a procedure or label, but print the contents of 
sta.ic cell F if BLDR thought it was a variable. If F started life as a variable, but had a 
procedure assigned to it you must call it by "@FtC" instead of "FtC". 



4. Resumable Files ' 

The file :>WATEE is a snapshot of a running program and can be saved for subseqent 
resumption or examination. You can create a copy of SWATEE by using COPY or, if you 
are in Sv/at, typing tL and giving a file name. This copies SWATEE to the named file and 
appends some information internal to Swat -- the current symbol table and break point 
data. 

There are several v/ays to restart resumable files: 

1. Press the boot button while holding down the keys for the file. 

2. Type the command (it is interpreted by the command processor) 
RESUME file 

If "file" is omitted SWATEE is assumed. 

RESUME/S file 

writes file onto SWATEE and invokes Swat. 

3. While in Swat, type tQ. and give a file name. The file is copied onto SWATEE and 
Swat's internal information is restored to whatever was saved by the tL command that 
created the file. If :he file was • created in some way other than tL, the internal 
information is reset to. an empty state. 



5. Invoking Swat with the Boot Button 

At any time, press the boot button while holding down the keys for the file Dumper.Boot 
(hopefully "DU"). This writes the existing menory onto SWATEE with the omission of page 
which is lost. Also the display word (420) is cleared. Finally, Swat is invoked. 
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6. Error Message Printing 

Swat contains some facilities to aid in printing error messages. Because the Swat resident is 
almost always present when a program is running, an error message can be printed by 
simulating a Swat "break," and letting the Swat program decipher the error specification ana 
print a reasonable message. 

If Swat is invoked by the #77403 trap instruction, the contents of ACO are taken to be a 
pointer to a BCPL string for a file name; AC1 is a pointer to table [ errCode%ClearBit; pi; 
p2; p3; p4.... ], where errCode (0 le errCode le 32000.) is an error code, the p's are 
'parameters," and ClearBit is either #100000 (clear the Swat screen before printing the 
message) or (do not clear). 

The intended use is with a BCPL procedure like: 

let BravoError(code, pi, p2, nil, nil, nil) be 

code=code%UserClearScreen Bit 

(table [ #77403; #1401 ] )("bravo.errors", lv code) 
// do a "finish" here if fatal error 

3 

The error messages file is a sequence of error messages, searched in a dumb fashion. An 
error message is: 

a. An unsigned decimal error number (digits only) 

b. Followed optionally by: 

C Always clear the screen before printing the message 

M (see below) 

L Log the error via the Ethernet. 

c. Followed by a <space>. 

d. Followed by text for the message, including carriage returns, etc. 
If you wish to refer to a parameter, give: 

$ 

followed by a digit to specify the parameter number (1,2,....) 

followed by a character to say how to print the parameter: 

O = octal 

D = decimal 

S = string (parameter is pointer to BCPL string) 
(example: $1D will print parameter 1 in decimal) 

e. Followed by $$ 

After the message is typed, if M was specified, the message "Type <control>K to kill, or 
<control>P to proceed.' 1 is typed out. 



7. Parity Error Information 

When the Alto detects a parity error, Swat is usually invoked to print a message about the 
details of the error. It then attempts to "log" the e ror with an Ethernet server responsible 
for keeping maintenance information, if the server is not operating, or if your Alto is not 
connected to an Ethernet with such a server, simply strike the "Swat" key (<blank-bottom>), 
and the familiar "#" will appear. 

In man\ cases, you will want to continue execution of your program after a parity error is 
detected. Simply type <controI>P to Swat. 
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8 . Installation 

Get the file InstallSwat.Run. Then invoke it to will create SWAT (the debugger), SWATEE 
(the swapout file for the user's memory image), and Dumper.Boot. InstallSwat.Run may be 
deleted after it has been run once. Use BOOTKEYS to discover the keys to depress for 
Dumper.Boot. If the answer is not "DU" invoke 

MOVETOKEYS Dumper.Boot DU 

9. Caveats 

1. Swat has about Ik of resident code in high core. This code is not changed when new 
subsystems come in. Therefore re-boot if it seems to be in a bad state. 

2. Instruction 77400B is used for breaks, and location 567B (in the trap vector) is used. 

3. Interrupt channel 8 (00400B) is used for keyboard interrupts. 

4. The resident disables interrupts on entry and enables them on exit (clobbering 500B) so 
putting breaks in non-interruptable code is dubious. 

5. A program fetching data from a broken location will get 77400B. 

6. While most interrupt routines are reasonably polite and always resume the interrupted 
code where it left off, the politeness of Swat's keyboard interrupt is entirely in the hands of 
the person at the controls. If he re-starts by saying tP, all goes well; but he may say ?G or 
tC. Therefore 

(1) You should disable the keyboard interrupt by anding 77377B into 453B during 

critical sections of code (once they are debugged). 

(2) Expect occasional anomalies after ?C or tG is used. 

7. The mappings between symbols and addresses are naive about BCPL's block structure 

a) If a symbol is defined twice or more you get the lowest address. 

b) An address is mapped into a procedure name plus a displacement for symbolic type 

out (e.g. for t T). If procedure A is defined inside procedure B, most of B's 
addresses will be typed as if they were A's. 

8. If a disk error prevents swapping the offending disk control block and label are displayed 
in the "boot-lights' manner. 

9. Locations 700 through 706 are used to save the registers before each swap. 

10. If a file created on a different disk is resumed by booting, invoking Swat may not work 
because SWAT and SWATEE may not reside at the same disk addresses on the different 
disks. This difficulty does not occur if the RESUME command is used. 
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Software and Utilities for Trident Disks: 
Tfs and Tfu • 



1. Introduction 

This document describes Bcpl-based software for operating any of the family of Trident 
disk drives attached to an Alto using a "Trident controller card" (the software presently 
deals with the T-80 and T-300 models). Hardware and diagnostic information can be found 
in the document "Trident disk for the Alto" (on <ALTODDCS>TRIDE:NT.EARS), by Roger 
Elates. 

The software documentation is divided into three parts: (1) a brief "how-to" section 
describing the software package available for operating the Trident; (2) a section describing 
the utility program' Tfu; and (3) a section describing the software package in more detail. 
There is a short revision history at the end. (Documentation for the Triex program, 
formerly included here, has been eliminated. Triex is now needed only for hardware 
checkout and is not required, during normal operation.) 

The Tfs rackage and utilities all assume that the disk is to be formatted with 9 sectors per 
track, 10z4 data words per sector. Thus a T-80 disk has a capacity (815 tracks, 5 surfaces, 9 
sectors, 1024 words per sector) of 2 6,675 pages or 37,555,200 words. A T-300 (19 surfaces 
rather than 5) has a capacity of 139,365 pages or 142,709,760 words; however, due to the 
restriction of virtual disk addresses to 16 bits, a single file system may utilize only about 47 
percent of this capacity, and it is necessary to construct multiple file systems in order to 
make use of the entire disk. 

Because of bandv/idth limitations, it is unwise to operate the Trident disk while the Alto 
display is on. Although the Tfs package will save the display state, turn it off, run the disk, 
and restore the display for every transfer, the user may prefer to turn the display off 
himself. The Tfs management of the display causes the screen to flash objectionably 
whenever frequent calls to Tfs are underway. 

The present version of the software conforms to the new Alto time standard and runs only 
mder Operating System version 14 or newer. 



2. Trident File System (Tfs) software package 

The software for operating the Trident disk is contained in <AIto>Tfs.Dm, and consists of 
the following relocatable files: TfsInit.Br, TfsBase.Br, TfsA.Br, TfsWrite.Br TfsCreate.Br, 
TfsClose.Br, TfsDDMgr.Br, TfsNewDisk.Br, TfsSwat.Br, and TriConMc.Br. The definitions 
file Tfs.D is also included. 

Included also are the Trident microcode source files, TriConMc.Mu and TriConBody.Mu. 
These are needed if you want to load other microcode into the Ram along with the Trident 
microcode. 

The LoadRam.Br file, formerly included as part of the Tfs, is now available as a separate 
package. 
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2.1. Initializing the microcode 

Operating the Trident requires special microcode that must be loaded into the RAM before 
disk activity can start. The procedure LoadRam will load the RAM from a table loaded 
into your program (it is actually part of TriConMc.Br). It will then "boot" the Alto in 
order to start the appropriate micro-tasks in the RAM. (This booting process is "silent" ~ 
it does not re-load Alto memory from the file Sys.Boot, but instead lets your program 
continue.) The standard way to call LoadRam to load the Trident disk microcode is: 

external DiskRamlmage 
external LoadRam 

let resull=LoadRam(DiskRamlmage, true) //Load and boot 
if result Is then 



k 



sf'The Alto has no RAM or Ethernet board.") 
Ws(" Cannot operate Trident") 
finish 
] 

After LoadRam has returned successfully, the code of LoadRam and TriConMc may be 
overlaid with data -- they are no longer needed. 

When exiting a program that has micro-tasks active in the RAM, it is helpful to "silently" 
boot the Alto so that all micro-tasks are returned to the ROM. If this is not done, 
subsequent use of the RAM may cause some running micro-task to run awry. To achieve 
the "silent boot," simply call the procedure TFSSilentBootQ at 'finish' time or as part of a 
\iser finish procedure'. 

For further information, consult the LoadRam package documentation. 

2.2. Initializing the Trident drive 

Once the RAM has been loaded, the Trident disk can be initialized. The procedure TFSInit 
will do this, provided that a legal file structure has previously been established on the drive 
(see Tfu Erase, below). The procedure returns a "disk object," a handle which can be used 
to invoke all the disk routines. This disk object (or "disk" for short) can be passed to 
various Alto Operating System procedures in order to open streams on Trident disk files, 
delete Trident disk files, etc. 

tridentDisk = TFSInit(zone, allocate [false], driveNumber [0], ddMgr [0], freshDisk [false]) 

zone You must provide a free-storage pool from which memory for the disk object 

and possibly for a buffer window on the disk bit table can be seized. The 
zone must obey the normal conventions (see Alto Operating System Manual); 
zones created by InitializeZone are fine. 

allocate This flag is true if you wish the machinery for allocating or de-allocating 

disk space enabled. If it is enabled, a small DDMgr object and a 1024-word 
buffer will be extracted from the zone in order to buffer the bit table (unless 
you supply a ddMgr argument, described below). 

driveNumber This argument, which defaults to 0, specifies the number of the Trident disk 
drive being initialized. If the drive is a T-300, the left-hand byte specifies 
the number of the file system to be accessed on that drive, in the range to 
2. (For further information, consult the section entitled 'Disk Format'.) 

ddMgr This argument, which defaults to 0, supplies a handle on a 'DiskDescriptor 
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Manager' (DDMgr) object, whose responsibility it is to manage pages of the 
Disk Descriptor (bit table), which, on the Trident, must be paged into and out 
cf memory due to its considerable size. If this argument*" is defaulted, a 
separate DDMgr will be created upon each call to TFSInit, at a cost of a little 
over 1024 vords. If you intend to have multiple Trident drives open 
simultaneously, you may conserve memory by first issuing the call 'ddMgr = 
TFSCreateDDMgr(zone) and then passing the returned pointer as the ddMgr 
argument in each call to TFSInit, thereby permitting the single ddMgr to be 
shared among all drives. (This argument is ignored unless the allocate 
argument is true.) 

freshDisk normally, TFSInit attempts to open and read in the DiskDescriptor file in 
order to obtain information about the file system. However, if freshDisk is 
true, this operation is inhibited and the corresponding portions of the disk 
object are set up with default values. This operation is essential for creating a 
virgin file system. 

triden :Disl. The procedure returns a disk object, or if the Trident cannot be operated 
for some reason. The most likely reasons are: 

1. No Trident disk controller plugged into the Alto. 

2. No such disk unit, or disk unit not on-line. 

3. Can't find SysDir, can't open DiskDescriptor, or DiskDescriptor format is 
incompatible. (These errors can't happen if freshDisk is true.) 

Important: If the AC power to drive is turned off or no drive is 
connected, it is not possible to operate any drive. (Drive need not be on- 
line, however.) This is due to a hardware bug that has been deemed too 
difficult to fix. 

Afler TFSInit has been executed, the code can be overlaid, as it is not used for normal disk 
operation. 

2.3. Closing the Trident disk 

When all operations on the disk are completed, the TFSClose procedure will insure that any 
important state saved in Alto memory is correctly written on the disk. This step can be 
omitted if the 'allocate' argument to TFSInit was false (assuming you don't mind the loss of 
the storage that was extracted from 'zone' by TFSInit). 

TFSClose(tridenlDisk, dontFree [false]) 

The second argument is optional (default=false), i nd if true will not permit the 
DiskDescriator Manager (DDMgr) to oe destroyed. This option is useful in conjunction 
with the 'ddMgr' argument to TFSInit. 

2 .4. Example 

Following is an example that uses the Trident disk system and demonstrates the procedures 
describee above. Note that the calls on operating system disk stream routines all pass a 
private zone to use for stream structures, rather than the default sysZone. The reason is 
that streams on Trident disks require large buffers (1024 words) which quickly exhaust the 
available space in sysZone. In addition, the stream routines will consume more stack space 
when operating the Trident disk than they do when operating the standard Alto disk. 
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Since the Alto OS does not know about Trident disks, a call to Swat will not properly wait 
for all Trident transfers to complete, with consequent undefined results. This problem is 
easily remedied through use of an assembly-language Swat context-switching procedure 
TFSSwat, which is included as part of the TFS package. The example shows how it is set 
up. 

//Example.bcpl -- TFS Example 

//Bldr Example TfsBase TfsA TfsWrite TfsCreate TfsClose TfsDDMgr 

// TfsSwat Tfslnit Load Ram TriConMc 

get "streams.d" 

external [ 

TFSInit 
TFSClose 
TFSSilentBoot 
Load Ram 
DiskRam Image 

Open File 
Closes 
Puts 
DeleteFile 

InitializeZone 

SetEndCode 

TFSSwatContextProc 

IvUserFinishProc 

lvSwatContextProc 

3 

static [ savedUFP; savedSCP; TFSdisk = ] 

let Trylt() be 

[ 

let driveNumber=0 

let zonevec= vec 3000 

let TFSzore = lnitializeZone(zonevec, 3000) 

//Initialize the RAM: 

let res=LoadRam(DiskRamImage, true) 

if res Is then [ WsfCannot load the RAM."); finish ] 

//Set up to cleanly finish or call swat 
savedUFP ~ ©IvUserFinishProc 
©IvUserFinishProc = MyFinish 
savedSCP = ©lvSwatContextProc 
©lvSwatContextProc = TFSSwatContextProc 

//Initialize the disk: 

TFSdisk = TFSInit(TFSzone, true, driveNumber) 
if TFSdisk eq then 

[ Ws("Cannot operate Trident disk"); finish ] 

//Reclaim space used bv initialization code: 

SetEnclCode(TFSlnit) //Overlay TFSinit, LoadRam, TriConMc 

//Now we are ready to operate the disk: 

DeleteFileC'Old.Bad", 0, 0, TFSzone, 0, TFSdisk) 
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let s=OpenFiIe("New.Good", ksTypeReadWrite, 0,0,0,0, 

TFSzone, 0, TFSdisk) 

for i=l to 1000 do 
for j=l to 1000 do Puts(s, $a) //Write a million bytes! 

Closes(s) 

finish 
] 



and MyFinishf) be 

[ 

if TFSdisk ne then TFSClose(TFSdisk) 
@lvUserFinishProc = savedUFP 
(ftlvSwatContextProc = savedSCP 
TFSSilentBoot() 
] 



3. Trident File Utility, Tfu 

The Tfu utility (saved on <Alto>Tfu.Run) is used to certify a new Trident pack for 
operation, to initialize a pack with a virgin file system, and to perform various file copying, 
deleting, and directory listing operations. Commands are given to Tfu on the command 
line: immediately following the word "Tfu" is a sub -command name (only enough characters 
of a sub-command are needed in order to distinguish it from other sub-commands), 
followed -b)' optional arguments. Several subcommands may appear on one command line, 
separated by vertical bars. Thus "TFU Drive 1 | Erase" will" erase drive 1. There must be a 
space on each side of the vertical bar. 

In what follows, an "Xfile" argument is a filename, perhaps preceded by a string that 
specifies which disk is to be used: 

smame.extension — use standard Alto system disk 

tn:name.extension -- use Trident drive n (n=0 to 7) 

name.extension -- use default disk (Trident) 

The "cefault disk" is always a Trident drive; the identity of the drive is set with the Drive 
command. 

TFU DRIVE driveMumber 

This command sets the default Trident drive number to use for the remainder of the 
command line. The default drive is effectively an 'argument' to the CERTIFY, 
ERASE, DIRECTORY, CONVERT, and BADS POTS commands. (On a T-300, file 
systems 0, 1, and 2 are specified as 'x', '40x\ and '100x', where Y is the actual unit 
number.) 

TFU CERTIFY [passes] 

This command initializes the headers on a virgin Trident disk pack, then runs the 
specified number of passes (default 10) over the entire pack, testing it using random 
data. Any sector exhibiting an uncorrectable ECC error, or correctable ECC errors 
on two or more separate occasions, is permanently marked unusable in the pack's bad 
page list. This information v/ill survive across all subsequent normal file system 
operations (including TFU ERASE), but may be clobbered by the Triex program. 
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This command should be executed on every new Tridentpack before performing any 
other operations (such as TFU ERASE). 10 passes of TFU CERTIFY are adequate 
for reasonably thorough testing, though more are recommended for packs to be used 
in applications requiring high reliability. The running time for TFU CERTIFY is 
approximately 3 minutes per pass on a T-80 and 9 minutes per pass on a T-300. 

TFU CERTIFY may be terminated prematurely by striking any character to get its 
attention, then typing 'Q\ Subsequent runs of TFU CERTIFY will not clobber the 
existing bad page information but rather will append to it. It is recommended 
(though not necessary) that TFU CERTIFY be executed before each TFU ERASE so 
as to "pick up any new bad spots that may have developed. 

TFU CERTIFY ordinarily asks you to confirm wiping out the disk before going 
ahead and doing so; however, the /N global switch may be used to indicate that no 
confirmation is necessary. 

TFU BADSPOTS 

Displays the addresses of all known bad spots on the disk pack mounted on the 
default drive. 

TFU ERASE [tracks] 

This command initializes (or reinitializes) a file system on the pack mounted on the 
default Trident drive, after asking you to confirm your destructive intentions 
(overridden by the /N global switch). The tracks argument specifies how many 
tracks of the drive are to be included in the file system; it defaults to the maximum 
possible. If smaller numbers are used, the initialization is correspondingly faster. In 
any case, tracks beyond the one specified are available for use outside the confines of 
the file system. (Note that one "track" is 45 pages; this corresponds to one cylinder 
on a T-80 and to nothing in particular on a T-300.) 

The disk pack should previously have been initialized and tested by means of the 
TFU CERTIFY command. 

TFU COPY Xfile <- Xfile 

This command copies a file in the direction of the arrow. The destination file may 
be optionally followed by the switch /C, in which case (provided it is a Trident disk 
file), the file will be allocated on the disk at consecutive disk addresses. (Note; More 
precisely, an attempt will be made to perform such an allocation. If the attempt 
fails, you will sometimes get an error message. The best way to verify that a file is 
contiguous is to use the "address" command, below.) 

TFU CREATEFILE Xfile pages 

This command creates a contiguous file named Xfile with length "pages." 
TFU DELETE Xfile 

This command deletes the given file. 

TFU DIRECTORY [Xfile] 

This command lists the directory of the default Trident drive on the file Xfile; if 
Xfile is omitted, each entry will be typed on the display. When the display fills up 
or the listing is finished, Tfu waits for you to type any character before proceeding. 
A somewhat more verbose listing can be achieved with TFU DIR/V. 

TFU ADDRESS Xfile 
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This command reads the entire file and prints a list (in octal) of virtual disk 
addresses of the file pages. Typing any character will proceed to the next output 
line. 

TFU CONVERT 

An incompatible change in the format of DiskDescriptor was made in the Tfs release 
of July 24, 1977. The current Tfs software will refuse to access Trident disks written 
in the old format (specifically, TFSInit will return zero). The TFU CONVERT 
command reformats the DiskDescriptor to conform to current conventions (it is a 
no-op if applied to a disk that has already been converted). Once you have 
converted all your Trident disks, you should take care to get rid of all programs 
loaded with the old Tfs, since the old Tfs did NOT check for version compatibility. 

TFU EXERCISE passes drive drive drive ... 

This command embarks on a lengthy "exercise" procedure; it is repeated 'passes' times 
(default=10), and uses the disk drives listed after 'passes' (if none are specified, all 
drives that are on-line are used). It operates by making a series of files (test.001, 
test.002 etc.) on the disk packs, and performing various copying, deleting, writing and 
positioning operations. The files are deleted when the exercise finishes. It is not 
essential mat the packs be fully erased initially; the procedure for building test files 
will try to fill up the disc, just short of overflowing. The test takes 20 to 30 
minutes per full pack per pass. 

One or more of the following global switches may be specified (i.e., a command of 
the form TFU/switcl. EXER...): 

/W Use a systematic data pattern when writing files, rather than arbitrary garbage. 

/C Carefully check the data read from the disk (implies /W). Use of this switch 
makes the test run considerably slower than normal. 

/E) Leave the display on during Tiident disk transfers. This causes data late errors 
to occur and thereby exercises the error recovery logic. 

/E Turn the Ethernet on during Trident disk transfers, with results similar to /D. 



4. The Tfs software package in more detail 

If programmers wish to interface the the Trident disk at levels lower than Operating System 
streams, the Tfs package provides an additional interface. The "disk" object created by 
TFSInit has a number of abstract operations defined on it, which the Tfs package 
implements. Documentation for these operations can be found in the Alto Operating System 
Manual in the section labeled "Disks and Bfs." The catalog of available procedures is: 

In TfsBase.Br and TfsA.Br: 

ActOnE)iskPages(disk, CAs, DAs, ....) 

RealDiskDA(disk, vda ) 

VirtualDiskDA(dis.k, ....) 

In TfsWrite.Br: 

WriteDiskPagesfdisk, CAs, DAs, ....) 
Assign DiskPagefdisk, vda)* 

In TfsCreate.Br 

CreateDiskFiIe(disk, name, ....)* 
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DeleteDiskPages(disk, CA, ....)* 
Release DiskPage(disk, vda)* 

The items with *'s following may be invoked only if the disk object was created with the 
'allocate' argument set to true. WriteDiskPages may be invoked even if 'allocate' is false, 
provided it never allocates new disk space. It should be noted that the standard Alto 
Streams package invokes WriteDiskPages even for files opened for reading only, and that 
TFSInii. uses Streams' to read in the DiskDescriptor. Hence it is necessary that all of the Tfs 
modules (TfsBase, TfsA, Tfs Write, TfsCreate, and TfsDDMgr) be loaded in order to avoid 
undefined 'external' references. However, after initialization is complete, the space occupied 
by TfsCreate and TfsDDMgr may be reclaimed if you do not intend to allocate or delete 
pages, and TfsWrite may be discarded if you are not using streams but rather are calling 
ActOnDiskPages directly. 

The TfsWrite and TfsCreate modules require that TfsDDMgr.Br (or some equivalent) be 
loaded. This module provides the standard primitives necessary for managing the 
DiskDescriptor. The DDMgr is an 'object', so it may be replaced by one of your ov/n 
devising so long as it provides equivalent operations. An example of this would be to 
manage pages ot the Disk Descriptor as part of a more general virtual memory mechanism 
(perhaps through use of the Alto VMem package). A complete description of the required 
DDMgr operations may be found as comments at the beginning of TfsDDMgr.BcpI. 

In addition to the standard "actions" defined in Disks.d, Tfs permits the following. These 
actions are defined in Tfs.d and are available only on Trident disks. 

DCreadLnD Read header, read label, no data. 

DCreadnD Check header, check label, no data. 

DCwriteLnD Check header, write label, no data. 

These actions neither read nor write the data record and therefore do not require a buffer 
to be provided. 

CreateDiskFile has a special feature for operating the Trident disks — an optional seventh 
argument. If this argument (pageBuf) is present, it is assumed to point to a 1024-word 
buffer that will be used to create the leader page for the file. This feature may be used to 
save stack space in CreateDisk file and/or to write interesting data into the portion of the 
leader page not used by the file system (only the first 2.56 words are used by the file system; 
the remainder has no standard interpretation). 

VirtualDiskDA returns filllnDA as the virtual address for a real disk address that is either 
illegal or outside the confines of the file system. 

The procedures for creating and destroying the disk object, TFSInit and TFSClose, were 
explained above. The procedure TFSWriteDiskDescriptor(disk) will write out onto the disk 
all vital information about the disk that is presently saved in memory. If you write 
programs that run the disk for extremely long periods of time, it is wise 'to write the disk 
descriptor occasionally. The only automatic call on TFSWriteDiskDescriptor is performed 
by TFSClose. 

TfsInit.Br contains a procedure TFSDiskModel(disk) that returns the model number (80 or 
300) of the drive referenced by the disk handle. This is useful in deciding whether to open 
a second or third file system on a T-300. 

A lower level of access is permitted with the routines TFSInitializeCbStorage, TFSGetCb, 
and TFSDoDiskCommand, analogous to the Bfs routines described in the Operating System 
Manual. Users of these routines may wish to retrieve source files for the Tfs package and 
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examine the definitions in Tfs.D and the actual disk operation in some detail. Sources are 
on <AltoSource>TfsSources.Dm. 

4.1. TFSNewDisk 

The TFSNewDisk procedure, defined in TfsNewDisk.Br, "erases" a disk (formatting it and 
making all its pages appear free) and creates a virgin Alto file system (SysDir and 
DiskDescriptcr). It is called by: 

success = TFSNewDisk(zone, driveNumber [0], diskSize [default]) 

The zone passed to TFSNewDisk must be capable of supplying about 3500 words of storage. 
If the drive is a T-300, the driveNumber may include a file system number (0 to 2) in its 
left byte, as is the case for TFSlnit. The diskSize argument is the number of disk pages to 
be included in the file system; it defaults to the maximum possible, which is all of a T-80 
or a little less than half of a T-300. TFSNewDisk returns true if successful. 

4.2. DiskFindHole 



The procedure DiskFindHole, in DiskFindHole.Br, can be used to locate a "hole" of 
available space in the disk bit table. The call: 

virtu;.lDA=DiskFindHcle(disk, nPages) 

will attempt to locate a contiguous hole n Pages long. If it fails, the procedure returns -1, 
otherwise the virtual disk address of the first page of the hole. 

In order to create a contiguous file, it is first necessary to create the minimal file with a 
leader page at the given disk address and then to use Operating. System or Tfs routines to 
extend the file properly. The first step is achieved by calling TFSSetStartingVDA(disk, vda), 
where 'vda' is the desired disk address (i.e., the result returned by DiskFindHole). This 
value will be used to bias the selection of an initial disk address for the leader page. Once 
the file is crea:ed, it is wise to extend it to its final length immediately, as other disk 
allocations might encroach on the "hole" that was located. 

For example, if we are usiig the Operating System, we might proceed as follows: 

hit nPages=433 //Number of data pages needed, 

let vda=DiskFindHole(TFSdisk, nPages+2) 

//(+2= 1 for leader, 1 for last page) 
if vda eq -1 then f WsP'Cannot find a hole big enough') ] 
TFSSetStartingVDA(TFSdisk, vda) 

let s=OpenFile("New.Contiguous",ksType\VriteOnly,0,verNew,0,0,0, 

TFSzone, 0, TFSdisk) 
Position Page(s, nPages) //Make the file the right length 
Closes^.) 



5. File structure on the Trident disk 

The file structure built on the Trident disk by Tfs (Trident File System) is as exact a copy 
of the Alto file structure built Bfs (Basic File System) as is possible. Certain exceptions are 
presen: due to hardware and microcode differences. The Alto Operating System Reference 
Manual should be consulted for all file formats and internal information not presented here. 
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5.1. Disk Format 

The Trident disk unit and pack, as it comes from Calcomp, is set up to run with the 
following parameters: 

number of cylinders: 815 

number of surfaces: 5 (T-80), 19 (T-300) 

TFU CERTIFY will format each surface in the standard Tfs format: 

number of sectors per track: 9 

he;ider words per sector: 2 

label words per sector: 10 

data words per sector: 1024 

Thus, a T-80 disk will have 9*5*815 = 2 6,675 sectors = 37,555,200 words. Sector will not 
be used by Tfs. All but sector will be available to the file system. 

Ordinarily, Tfs utilizes only the first 383 cylinders (= 65,493 sectors = 67,064,032 words) of 
a T-300 disk. This is the largest integral number of cylinders that can be addressed using a 
16-bit virtual disk address. The 16-bit virtual address limitation is deeply embedded in all 
existing higher-level Alto file system software, so changing the Tfs interface to permit a 
larger virtual address space would be impractical. 

Instead, Tfs permits one to obtain another, entirely independent disk object for referencing 
the second 383 cylinders of the same T-300, thereby permitting a separate, self-contained 
file system to be constructed. This is done by passing a T in the left byte of the 
YlriveNumber' argument to TFSInit or TFSNewDisk (that is, drive '#400' refers to the 
second file system on a T-300 pack mounted on drive 0). A third file system (number '2\ 
drive '#1000 v ) may also be constructed, but it contains only 49 cylinders (- 8379 pages, only 
6 percent of the disk's total capacity), so doing so is probably not worthwhile. 

5.2. Disk Header and Label 

On the Trident, a real disk address requires two words to express, rather than the single 
word on the Diablo 31. Also, microcode considerations gave rise to a reordering of the 
entries in the Label. The result is that both the header and label formats are different for 
the Trident. The Trident format follows. If you are interested in this level of detail, the 
file Tfs.d (contained within <Alto>Tfs.dm) should be consulted. 

// disk header 
structure DH: 

track word 
head byte 
sector byte 

// disk label 
structure DL: 

fileid word 1FID 
pack ID word 
numChars word 
page Number word 
previous @DH 
next @DH 

] 

manifest 1DL = size DL/16 
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5.3. Disk Descriptor 

Every valid Tfs disk has on it two files which must contain the state information necessary 
to maintain the integrity of the file system. The Tfs system directory, "SysDir.", is identical 
in format and purpose with its Bfs counterpart. However the Tfs disk descriptor file, 
"DiskDescriptor. 1 , while identical in purpose, is formatted differently to allow easy 
manipulation of the bit table (which, for the Trident, has to be paged in and out of 
memory). This difference in format should not be evident to even low-level Trident users 
(unless you writ: your own DDMgr), but is mentioned here for completeness. 

5.4. Bad Page Table 

Tfs and Tfu observe the standard Alto file system convention of recording -2's in the labels 
of all known bad pages. However, if this were the only location of such information, 
"erasing" a disk (to create a virgin file system) would require two passes over the entire 
disk: one to collect the addresses of all known bad pages and one to mark all remaining 
pages deleted. This would require an excessive amount of time, particularly on a T-300. 

A duplicate table of known bad pages is therefore recorded on physical page zero (- 
cylinder 0, head 0, sector 0) of the disk. This page is not available to the file system for 
other reasons having to do with end-of-file detection. The format of the table is given by 
the BPL structure, which is defined in Tfs.d. Note that the entries are REAL disk addresses 
and can therefore refer to any page on the disk regardless of whether or not such a page is 
accessible through the file system. (A T-300 has only one bad page table, even if it 
contains several file systems.) 

The TFU CERTIFY command is responsible for testing the pack and building the bad pag,e 
table. The TFSNewDisk procedure (called by TFU ERASE) is careful not to clobber this 
information but rather to propagate it to the other places where it is needed (namely, the 
disk bit table and the labels of the bad pages themselves). As a result, the bad page 
information, once initialized, will survive across all normal operations on the disk, including 
"erase" operations. 

There does not presently exist any facility for manually appending to this list when new bad 
pages are discovered. Experience to date with the Trident disks (which provide correction 
for error bursts of up to 11 bits in length^ has shown that such a facility is probably not 
needed. Thorough testing of disks (using TFU CERTIFY) is recommended before putting 
them into regular use, however. 



6. Revision History 

July 24, 1977 

Incompatibilities: 

The forms t of DiskDescriptor has changed. The new Tfs cannot access old disks or vice 
versa. See description under "TFU CONVERT". 

There is now another file, TfsA.Br, that is logically part of TfsBase.Br and must be loaded 
along with it. It contains assembly-language coue formerly included as "tables" in 
TfsBase.Br. 

New Features: 

Partial support for T-300 disks. 
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Conforms to new conventions for maintaining addresses of known bad pages. 

TFSlnit checks for valid SysDir leader page and DiskDescriptor version. 

Count of bit table discrepancies added to DiskDescriptor. (These are pages falsely claimed 
to be free in the bit table.) 

VirtualDiskDA returns filllnDA for illegal real disk addresses. 

Additional Trident-specific disk actions. 

Tfs is now entirely reentrant, so it is safe for the Idle() procedure to give control to another 
process that in turn calls Tfs procedures. 

October 21, 1977 

Incompatibilities: 

The former TfsWrite module has been broken into four pieces: TfsWrite, TfsCreate, 
TfsClose, and TfsDDMgr. In most applications, all four must be loaded. 

The 'sharedBT argument to TFSlnit has been replaced by a 'ddMgr' argument. The 
mechanism for sharing a bit table buffer among multiple drives has been entirely changed. 
(Programs that omit this argument are unaffected by the change.) 

The TFSCreateVDA static has been removed. In its place is a new procedure 
TFSSetStartingVDA(disk, vda) that serves the same purpose. 

The syntax of the TFU EXERCISE command has been changed. It is now TFU EXERCISE 
<passes> < list of drives>', and < 1 ist of drives> defaults to all drives that are on-line. 

New features: 

Complete support for T-300 disks. In conjunction with this, the TFSDiskModel procedure 
has been added. 

It is now possible for DiskDescriptor pages to be managed externally (perhaps through some 
sort of virtual memory mechanism) by use of a user-defined 'Disk Descriptor Manager' 
object. 

TFSSilentBoot procedure added. 

November 9, 1977 

Incompatibilities: None. 

New features: 

TFU CERTIFY and TFU BADSPOTS commands added. TFU CERTIFY initializes the 
headers on a virgin disk pack and then runs repeated tests over the entire pack, permanently 
recording any bad spots that it finds. This command replaces all the normal uses of the 
Triex program, documentation for which has been removed. 

Microcode modified for more efficient reading on Alto-IIs (by about 25%). 

February 26, 1978 

Incompatibilities: Software updated to new time standard; will not run under OS versions 
earlier than 14. 
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New features: Microcode source now in two parts, to facilitate combining it with other 
microprograms. 
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ViewData — 2D projections of 3D data on Display Screen 



ViewData is a BCPL subsystem that will draw a picture of a file of data on your dispaly 
screen, and allow you to interactively control your point of view on the data. It handles 
only a two-dimensional array of single-word values (i.e. a three-dimensional surface, a 
function of two variables evaluated over a regular finite grid). Here is a list of features: 

1) ViewData accepts input in the simplest possible file format: an optional header of any 
number of words (with any contents, which are ignored), followed by a block of (signed) 
data words of any size, with any dimensions. 

2) ViewData takes all parameters from a dialog with the user via keyboard and mouse. 
By specifying different header sizes and dimension sizes, the user can exercise limited 
control over the selection of data from his file. 

3) ViewData takes all graphical parameters from screen points clicked with the mouse. 
A point of view is specified by Clicking the screen positions of three corners of the data 
array. Zooming is accomplished by clicking opposite corners of the rectangle to be 
expanded. Prompts appear below the plot region to indicate what points and/or switches 
to click. 

4) ViewData contains a call to DCBPress to allow generation of a one-page output file 
with a picture of your data. This can be annotated by Markup and printed by an 
appropriate server. With PressEdit, it can be editted into a report. 

5) ViewData uses the new PlotStream package (to be released soon) to provide a display 
interface which is transparent to the average programmer; thus the program is easily 
modified to better suit your data viewing requirements. 

6) ViewData is reasonably small, especially if one deletes unneeded routines from the 
various files which are loaded with it (MathUtil, SDialog, UtilStr, PlotStream, 
FractionProduct, DCBPress). 

Getting and Running Viev/data: 

Use FTP to retreive viewdata.run. If you need some sample data, use the FTP Load 
command to get Test.Data from ViewData.Dm (stored with sources). Execute ViewData and 
default all the parameters with CR to get a sample display. Using the mouse, follow the 
instructions of the prompts to zoom, redraw in a new orientation, or overview (zoom back 
out to the highest level). After you finish by pressing all three mouse buttons at once, you 
have the options of producing a press file, restarting (possibly with a new data file), or 
quitting. 
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Making a nev/ Alto disk 



This document describes procedures for creating a new disk, either by copying the disk or 
by using the File Transfer Program. It may be helpful to refer to documentation for 
Copydisk and FTP. 

I. 

The normal way to obtain a new, clean disk is to copy one of the Basic Alto Disks (Non- 
Programmer's, BCPL Programmer's, Mesa Programmers, or Proofreaders) using Copydisk. 
You will need an Alto with a dual disk drive. Place the Basic Alto Disk into disk drive 0. 
Place the new disk into disk drive 1. Type 

>NetExec 
>CopyDisk 
*Copy from: clpO 
Copy to: dpi 

Copydisk will copy disk to disk 1, overwriting everything on the disk. 

You can also copy the Basic disk from one Alto to another over the Ethernet. The 
CopyDisk documentation explains how to do this. 

There should be a date on the label of the Basic Alto Disk which tells when it was last 
updated. 

An alternative way of building a new disk from scratch is to erase it by means of the 
Install procedure, then use FTP to retrieve the subsystems and other files that you need. 

First, bootstrap the NetExec by booting the Alto with the BS and single- quote keys 

depressed. Then type: 

>Sys.boot 

This will load a copy of the OS from the network. When it starts up, it will ask you if you 
want to install the OS; respond 'Y'. 

Install will ask if you want the long dialog; respond *Y\ Then it will ask if you want to 
erase a disk. Reply 'Y'. It will ask you for the name of the local file server and the name 
of the directory on that server from which to obtain files (the correct response to the latter 
question is usually 'Alto'). Finally, it will ask the usual questions about your name, the disk 
name, and the password. 

When Install has finished initializing the disk it will run FTP to obtain the Executive. 
Now, to obtain current versions of the 'basic' software type 
>ftp file-server ret/c <a!to>newdisk.cm 
>@newdisk.cm@ 

where 'file-server' is the name of your local file server. 

After this has completed, to obtain additional software for a 'basic non-programmer's disk' 

type 

>@npdisk.cm@ 

To obtain additional software for a 'basic BCPL programmer's disk' type 
>@pdisk.cm@ 

To obtain additional software for a 'basic Mesa programmer's disk' type 
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>@rnesadisk.cm@ 
II. 

You can copy files from your old disk to the new one in two ways. One is to put them 
Dnto a file server and retrieve them with FTP. If there are many, it is a good idea to 
package them into a dump file. The other way is to copy them from the old disk on one 
Alto to the new disk on another Alto. On your new disk, type 
>ftp 

On the Alto with the old disk, type 

>ftp <Host name> store/c <filenamel> <filename2> ... 

<Host name> is the name of the Alto which has the new disk. 

The easiest way to specify and transfer lots of files is to use DDS (if you have it on your 
old disk) to select trie desired files, then issue the <Send to ...> command and type in the 
name of the Alto with your new disk. 

Without DDS, a way to specify lots of files is to obtain a file with all your file names by 

typing 

>*<control-XXcontrol-U>< return >< return > 

This will automatically invoke Bravo and read in 'line.cm'. You may then edit line.cm to 
exclude the files which you do not want to transfer and insert the necessary FTP commands, 
thereby creating a command file which may be invoked in the usual way. For example, at 
the beginning of the file insert 
ftp <Host name> store/c 

then delete everything except the files which you want to transfer. 'P'ut the command string 

onto a file. 'Q'uit out of BRAVO and type 

>@foo@ 

where Too' is the name of the file which you just created with BRAVO. The selected files 
will be sent to the waiting Alto with the new disk. 

Executing either variant of procedure I to erase and initialize your disk, followed by 
procedure II to transfer all oi your files using FTP, is a good way to compact a fractured 
disk. 
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1. PARC Information 



1.1. Getting Started 

Each administrative group in Pare handles disk pack allocation differently. Ask your 
secretary how to get a disk. 

A set of BASIC ALTO DISKS is kept in a rack near the Altos in the Maxc room. These 
disks are recreated once a week. The date when a disk was last created is on its label. 
Procedures for copying a Basic Alto Disk to your new disk are described in the "new disk" 
section of this document. 

1.2. MAXC Directories for Alto Software 

The <ALTODOCS> directory contains documentation for the subsystems and subroutine 

packages. 

The <ALTO> dire;tory contains current versions of all the Alto programs. Programs are 
normally kept in executable form; thus the CopyDisk program appears as 
(ALTO>CopyDisk.Run. In addition to the executable file, some programs also have a 
symbol file on <ALTO>. The symbol file for CopyDisk is <ALTO>CopyDisk.Syms. This 
fi e is useful to the author when something goes wrong with a subsystem, but it is not 
normally reeded by users. Subsystems which need- more than one file, either because they 
have overlays or because they need data files, should have the individual files stored, 
together with a command file which may be run to retrieve each file via FTP. The 
command file should have the extension .CM. Definition files have the extension .D. 
These files are useful only to programmers. 

Subroutine packages are kept on <ALTO> with an extension of .BR or as "dump" files 
(extension .DM) if several files belong together as a package. 

The <ALTOSOUPCE> directory contains the source files for the subsystems and subroutine 
packages. It also contains the PUB files for the documentation which is on <ALTODOCS>. 

1.3. Alto Software Maintenance Procedure 

The mainlainer of a subsystem or subroutine package handles a new or revised release in the 
following manner: 

A. Copy a dump file with a name of the form SubsystemName.DM and the following 
contents to <ALTOSOURCE>: 

1) The source files from which the subsystem may be created. 

2) The command files which are needed to create the subsystem from the enclosed 
source, unless the creation procedure is "obvious." The following are the usual 
ingredients: 

a) A command file containing statements to compile the enclosed source. 
Compiler messages should be written to a file. For example: 

BCPL/F FOO.BCPL. 

The filename should be in the format, COMPILEsubsysName.CM. 
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b) A command file to load the files which were produced in step a. For 
example: 

BLDR FOO 

The filename should be in the format, LOADsubsysName.CM. 

If the subsystem is small, the two command files may be combined 
into one. The name should be in the format, 
CREATEsubsysName.CM. The following example will create the 
package for subsystem FOO. 

BCPL/F FOO.BCPL; BLDR FOO 

c) A command file containing statements to save all relevant files in 
subsysName.DM, e.g. the file DUMPFOO.CM would contain; 

DUMP FOO.DM FOO.BCPL CREATEFOO.CM DUMPFOO.CM 

B. When you have a change to make to documentation, or wish to introduce new 
documentation into the system, the following three steps are required: 

1. Retrieve the relevant .PUB file from <ALTOSOURCE>. The file name is in the 
format, sys.PUB, where 'sys' is the name of the subsystem or subroutine package. If you are 
creating brand new documentation, start with the file 
<ALTOSOURCE>ALTODOCTEMPLATE.PUB, which contains the necessary Pub 
incantations and some instructions to authors. 

2. Edit the pub file. Pass it to PUB— a .TTY version of the documentation will be 
produced. 

3. When you are finished, copy the pub file back to <ALTOSOURCE>, and copy 
the .TTY version to <ALTODOCS>. 

Please be sure to copy the pub files from <ALTOSOURCE> afresh each time you edit them, 
because they may have been edited to produce expurgated versions (for distribution outside 
PARC), to produce indexes, remedy formatting problems, etc. 

Please try to avoid needless references to PARC or Maxc facilities. For example, it is 
frowned upon to mention the <ALTO> directory as a place to find something. That is 
assumed for PARC users. Similarly, avoid needless references to GEARS or EARS. 

C. Copy files needed for the new release to <ALTO>. 

D. Send a message to Alto users describing the changes which will be effective with this 
release. The list of Alto users is on the file, <Secretary>AltoUsers.DL. The subject of the 
message should be the name of the subsystem or subroutine package. Try to keep the 
message short. 

Passwords: The password to all Alto-related directories on MAXC is ISFWGI. Software 
maintainers are cautioned to alter only files for which they will take responsibility. Feel 
free to archive old versions, but please leave the current version of all files. 

1 .4. Alto Documentation 

Formal documentation is provided in two forms: a "perusal" form, which can be 
conveniently typed at a Tl or VTS terminal on Maxc or perused with Bravo on an Alto, and 
a "notebook" form, which can only be printed on Ears or a Press printer, and may have 
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fancy illustrations or fonts in it. Informal "message" documentation can be extracted from 
the <ALTO;»MESSAGE.TXT file. 

A. The "perusal" documentation is always stored on <ALTODOCS> under a file name like 
sys.TTY, where "sys" is the name of the subystem or package you are interested in. For 
example, the documentation for a subroutine package, FOO, would be found on 
<ALTODOCS>FOO.TTY. There is one exception to this rule: for very simple subsystems 
the documentation is in <ALTODOCS>SMALLSUBSYSTEMS.TTY. 

B. The "notebook" documentation is packaged in larger packages to reduce storage overhead 
and to provide more manageable sets; of documentation for printing. Currently, the 
following files are maintained in notebook-style: 

Alto User's Handbook. This document is available only as a printed, bound manual. 
It contains the Non-Programmer's Guide to the Alto, and manuals for Bravo, 
Markup, Draw, and. IHTP. 

BRAVO.EARS, MARKUP.EARS, DRAW.EARS, NSIL.EARS, GYPSY.EARS. 
Currently, these subsystems have their own separate Ears documentation. 

OS.EARS. Operating System manual. 

BCPL.EARS. BCPL manual. 

SUBSYSTEMS.EARS, .PRESS. Documentation for most Alto subsystems. These are 
arranged alphabetically, with headings to indicate which system is being 
described. A directory at the front of the file contains documentation about 
very simple subsystems. The last section of this manual contains special 
information relating to Altos at PARC—where to find the software, how to 
maintain it, etc. 

PACKAGES.EARS, .PRESS. This contains documentation for the software packages 
available for the Alto. A directory at the front of the file contains 
documentation about very simple packages. 

ALTOHARDWARE.EARS, .PRESS. This is the "hardware" manual for the Alto. 

TRIDENT.EARS. Documentation for the Trident disk controller. 

These files are formatted, and should therefore be printed with 

(©EARS FOO.EARS — or - PRESS FOO.PRESS 

C. The file < A LTO> MESSAGE.TXT contains all of the information which has been sent to 
Alto users with SNDMSCJr. Information about recent changes to a specific subsystem may be 
selected by using the.'subject string' option of the MSG subsystem. For example, you may 
type 

MSG <ALTO>MESSAGE.TXT T S FOO 

Or you can read the entire file by saying 

File: <ALTO> ME SSAGE.TXT 

to READMAIL. Every six months this file will be purged and its old contents left on the 
next version of OLDMESSAGE.TXT. 
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1.5. Command Files 

In addition to ths subsystems, packages, and definition files, the following command files 
may be found on the <ALTO> directory: 

NEWDISK.CM: creates a minimal system on a new disk. See the NewDisk 
procedure, in the Alto Subsystems manual. 

DISTDISK.CM: creates the disk for distribution to other Xerox sites. NEWDISK.CM 
must be run first. 

MESADISK.CM: creates a Basic Mesa Disk. NEWDISK.CM must be run first. 

NPDISK.CM: creates a Non Programmer's Disk. NEWDISK.CM must be run first. 

PDISK.CM: creates a Programmer's Disk. NEWDISK.CM must be run first. 

PROOFDISK.CM: creates a Proof Reader's Disk. NEWDISK.CM must be run first. 
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<ALTO> 138 

<ALTODOCS> 138 

<ALTOSOURCE> 138 

<control>P 120 

Analyze 5 

ANSRV 2 

ASM 2, 9 

BCPL 2 

BLDR 2, 3, 9 

Boot Files 12 

BOOTFROM 3, 51 

Booting 12 

BOOTKEYS 3, 52 

BRAVO 2, 106 

BUILDBOOT 2, 14 

CallSubSys . 49 

CHAT 2, 16, 53 

CLEANDIR 2 

Com.Cm 49 

command processing 49 

COPY 3, 51 

COPYDISK 2, 19, 136 

CREATEFILE 2, 28 

DDS 2, 29 

DEFMJLT.ED 3 

DELETE 3, 51 

DIAGNOSE 3, 51 

disk 112 

DiskBoot.Run 14 

display protocol 18 

DMT 39 

DMT.BOOT 3 

Documentation 139 

DPRINT 3 

DRAW 3 

DUMP 3, 52 

Dump Format 53 

Dumper.Boot 115, 119, 121 

EARS 74, 106, 107 

EMPRESS 3, 44 

EtherBoot 53 

EtherNet loader 14 

EXECUTIVE 3, 49 

Executive Commands 51 

FEARS 3 

FILESTAT 3, 53 

FIND 3 

FTP 3, 53, 57, 136 

GEARS 3, 74 

Gobble 5 

GPR 5 

illustrator 2,4 
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INSTALL 3, 52 

InstallSwat.Run 121 

LISTSYMS 3 

LOAD 3, 52 

LOGIN 3, 52, 60 

MAILCHECK 3, 89 

MARKUP 4 

MAXC 16 

MAXC: mail 3 

memory diagnostic 3 

MICRO ■ . 4 

microcode assembler 4, 90 

microcode loader 103, 110 

MOVETOKEYS 4 

MU 4, 90, 103, 110 

NETEXEC 4, 53 

new disk 136 

NEWDISK 6 

OEDIT 4, 98 

ORAM . . ' . 4 

PACKMU 4, 103 

PARC Information 138 

PARCALTOS 6 

Parity error 120 

eek 39 

PEEKPUP 4, 105 

PeekSum . . 39 

PPR 5 

PREPRESS 4 

Press file 4, 106, 107 

Press files 3 

PRESSEDIT 4, 106 

PRINT 4, 107 

printing 74 

PROOFREADER 4 

Pup 105 

PUP Telnet 2, 16 

PUT 4 

QED 108 

QUIT 3, 51 

RAM 4, 103, 110 

RAMLOAD 4, 110 

Read Pram 103 

READPRESS 4 

RELEASE 3, 52 

Rem.Cm 49 

RENAME . 3, 4, 51 

RESUME 5,53,115,119 

RPRAM 4, 103 

SaveState subroutine 15 

SCAVENGER 4, 53, 112 

SETTIME . . 3, 52, 114 
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SIL 5 

Software Maintenance Procedure 138 

SORT 5 

STANDARDRAM 3, 52 

SWAT 5, 13, 115, 121 

SWATEE 121 

SYS.BOOT 5, 15 

TFS 5 

TFU 5 

time 114 

Trident disk software 5 

TRIEX 5 

TYPE . 3, 51 

User.Cm 53 

VIEWDATA 5 



